1.. _VendorDocumentation: 2 3==================== 4Vendor Documentation 5==================== 6 7.. contents:: 8 :local: 9 10The instructions on this page are aimed at vendors who ship libc++ as part of an 11operating system distribution, a toolchain or similar shipping vehicles. If you 12are a user merely trying to use libc++ in your program, you most likely want to 13refer to your vendor's documentation, or to the general user documentation 14:ref:`here <user-documentation>`. 15 16.. warning:: 17 If your operating system already provides libc++, it is important to be careful 18 not to replace it. Replacing your system's libc++ installation could render it 19 non-functional. Use the CMake option ``CMAKE_INSTALL_PREFIX`` to select a safe 20 place to install libc++. 21 22 23The default build 24================= 25 26The default way of building libc++, libc++abi and libunwind is to root the CMake 27invocation at ``<monorepo>/runtimes``. While those projects are under the LLVM 28umbrella, they are different in nature from other build tools, so it makes sense 29to treat them as a separate set of entities. The default build can be achieved 30with the following CMake invocation: 31 32.. code-block:: bash 33 34 $ git clone https://github.com/llvm/llvm-project.git 35 $ cd llvm-project 36 $ mkdir build 37 $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" # Configure 38 $ ninja -C build cxx cxxabi unwind # Build 39 $ ninja -C build check-cxx check-cxxabi check-unwind # Test 40 $ ninja -C build install-cxx install-cxxabi install-unwind # Install 41 42.. note:: 43 See :ref:`Vendor Configuration Options` below for more configuration options. 44 45After building the various ``install-XXX`` targets, shared libraries for libc++, libc++abi and 46libunwind should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and headers in 47``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See the instructions below for information on how 48to use this libc++ over the default one. 49 50In the default configuration, the runtimes will be built using the compiler available by default 51on your system. Of course, you can change what compiler is being used with the usual CMake 52variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build 53explained below makes this task easy. 54 55Using the just-built libc++ 56--------------------------- 57 58Most compilers provide a way to disable the default behavior for finding the standard library and 59to override it with custom paths. With Clang, this can be done with: 60 61.. code-block:: bash 62 63 $ clang++ -nostdinc++ -isystem <install>/include/c++/v1 \ 64 -nostdlib++ -L <install>/lib -lc++ \ 65 -Wl,-rpath,<install>/lib \ 66 test.cpp 67 68The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path, which causes the system's 69dynamic linker to look for libc++ in ``<install>/lib`` whenever the program is loaded. 70 71 72The Bootstrapping build 73======================= 74 75It is possible to build Clang and then build the runtimes using that just-built compiler in a 76single CMake invocation. This is usually the correct way to build the runtimes when putting together 77a toolchain, or when the system compiler is not adequate to build them (too old, unsupported, etc.). 78To do this, use the following CMake invocation, and in particular notice how we're now rooting the 79CMake invocation at ``<monorepo>/llvm``: 80 81.. code-block:: bash 82 83 $ mkdir build 84 $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" \ # Configure 85 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \ 86 -DLLVM_RUNTIME_TARGETS="<target-triple>" 87 $ ninja -C build runtimes # Build 88 $ ninja -C build check-runtimes # Test 89 $ ninja -C build install-runtimes # Install 90 91.. note:: 92 - This type of build is also commonly called a "Runtimes build", but we would like to move 93 away from that terminology, which is too confusing. 94 95 - Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not* 96 freshen the cmake cache of any of the enabled runtimes. 97 98 99.. _Vendor Configuration Options: 100 101Vendor Configuration Options 102============================ 103 104This section documents configuration options that can be used by vendors when building the library. 105These options provide a great deal of flexibility to customize libc++, such as selecting the ABI in 106use, whether some features are provided, etc. 107 108.. warning:: 109 Many of these CMake options are tied to configuration macros with a corresponding name in the source 110 code. However, these configuration macros are not intended to be customized by users directly, since 111 many of them require the library to be built with a matching configuration. If you don't build libc++ 112 yourself, you should not use the options documented here. 113 114General purpose options 115----------------------- 116 117.. option:: LIBCXX_INSTALL_LIBRARY:BOOL 118 119 **Default**: ``ON`` 120 121 Toggle the installation of the library portion of libc++. 122 123.. option:: LIBCXX_INSTALL_HEADERS:BOOL 124 125 **Default**: ``ON`` 126 127 Toggle the installation of the libc++ headers. 128 129.. option:: LIBCXX_INSTALL_MODULES:BOOL 130 131 **Default**: ``ON`` 132 133 Toggle the installation of the experimental libc++ module sources. 134 135.. option:: LIBCXX_ENABLE_SHARED:BOOL 136 137 **Default**: ``ON`` 138 139 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or 140 `LIBCXX_ENABLE_STATIC` has to be enabled. 141 142.. option:: LIBCXX_ENABLE_STATIC:BOOL 143 144 **Default**: ``ON`` 145 146 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or 147 `LIBCXX_ENABLE_STATIC` has to be enabled. 148 149.. option:: LIBCXX_LIBDIR_SUFFIX:STRING 150 151 Extra suffix to append to the directory where libraries are to be installed. 152 This option overrides `LLVM_LIBDIR_SUFFIX`. 153 154.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL 155 156 **Default**: ``OFF`` 157 158 Do not export any symbols from the static libc++ library. 159 This is useful when the static libc++ library is being linked into shared 160 libraries that may be used in with other shared libraries that use different 161 C++ library. We want to avoid exporting any libc++ symbols in that case. 162 163.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 164 165 **Default**: ``ON`` except on Windows when using MSVC. 166 167 This option can be used to enable or disable the filesystem components on 168 platforms that may not support them. For example on Windows when using MSVC. 169 170.. option:: LIBCXX_ENABLE_WIDE_CHARACTERS:BOOL 171 172 **Default**: ``ON`` 173 174 This option can be used to disable support for ``wchar_t`` in the library. It also 175 allows the library to work on top of a C Standard Library that does not provide 176 support for ``wchar_t``. This is especially useful in embedded settings where 177 C Standard Libraries don't always provide all the usual bells and whistles. 178 179.. option:: LIBCXX_ENABLE_TIME_ZONE_DATABASE:BOOL 180 181 **Default**: ``ON`` 182 183 Whether to include support for time zones in the library. Disabling 184 time zone support can be useful when porting to platforms that don't 185 ship the IANA time zone database. When time zones are not supported, 186 time zone support in <chrono> will be disabled. 187 188.. option:: LIBCXX_INSTALL_LIBRARY_DIR:PATH 189 190 **Default**: ``lib${LIBCXX_LIBDIR_SUFFIX}`` 191 192 Path where built libc++ libraries should be installed. If a relative path, 193 relative to ``CMAKE_INSTALL_PREFIX``. 194 195.. option:: LIBCXX_INSTALL_INCLUDE_DIR:PATH 196 197 **Default**: ``include/c++/v1`` 198 199 Path where target-agnostic libc++ headers should be installed. If a relative 200 path, relative to ``CMAKE_INSTALL_PREFIX``. 201 202.. option:: LIBCXX_INSTALL_INCLUDE_TARGET_DIR:PATH 203 204 **Default**: ``include/c++/v1`` or 205 ``include/${LLVM_DEFAULT_TARGET_TRIPLE}/c++/v1`` 206 207 Path where target-specific libc++ headers should be installed. If a relative 208 path, relative to ``CMAKE_INSTALL_PREFIX``. 209 210.. option:: LIBCXX_SHARED_OUTPUT_NAME:STRING 211 212 **Default**: ``c++`` 213 214 Output name for the shared libc++ runtime library. 215 216.. option:: {LIBCXX,LIBCXXABI,LIBUNWIND}_ADDITIONAL_COMPILE_FLAGS:STRING 217 218 **Default**: ``""`` 219 220 Additional compile flags to use when building the runtimes. This should be a CMake ``;``-delimited list of individual 221 compiler options to use. For options that must be passed as-is to the compiler without deduplication (e.g. 222 ``-Xclang -foo`` option groups), consider using ``SHELL:`` as `documented here <https://cmake.org/cmake/help/latest/command/add_compile_options.html#option-de-duplication>`_. 223 224.. option:: LIBCXX_ADDITIONAL_LIBRARIES:STRING 225 226 **Default**: ``""`` 227 228 Additional libraries libc++ is linked to which can be provided in cache. 229 230.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 231 232 **Default**: ``ON`` 233 234 Build libc++ with exception support. 235 236.. option:: LIBCXX_ENABLE_RTTI:BOOL 237 238 **Default**: ``ON`` 239 240 Build libc++ with run time type information. 241 This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF. 242 243.. option:: LIBCXX_INCLUDE_TESTS:BOOL 244 245 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``) 246 247 Build the libc++ test suite, which includes various types of tests like conformance 248 tests, vendor-specific tests and benchmarks. 249 250.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 251 252 **Default**: ``ON`` 253 254 Build the libc++ benchmark tests and the Google Benchmark library needed 255 to support them. 256 257.. option:: LIBCXX_ASSERTION_HANDLER_FILE:PATH 258 259 **Default**:: ``"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"`` 260 261 Specify the path to a header that contains a custom implementation of the 262 assertion handler that gets invoked when a hardening assertion fails. If 263 provided, this header will be included by the library, replacing the 264 default assertion handler. If this is specified as a relative path, it 265 is assumed to be relative to ``<monorepo>/libcxx``. 266 267ABI Specific Options 268-------------------- 269 270The following options allow building libc++ for a different ABI version. 271 272.. option:: LIBCXX_ABI_VERSION:STRING 273 274 **Default**: ``1`` 275 276 Defines the target ABI version of libc++. 277 278.. option:: LIBCXX_ABI_UNSTABLE:BOOL 279 280 **Default**: ``OFF`` 281 282 Build the "unstable" ABI version of libc++. Includes all ABI changing features 283 on top of the current stable version. 284 285.. option:: LIBCXX_ABI_NAMESPACE:STRING 286 287 **Default**: ``__n`` where ``n`` is the current ABI version. 288 289 This option defines the name of the inline ABI versioning namespace. It can be used for building 290 custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues 291 with other libc++ versions. 292 293 .. warning:: 294 When providing a custom namespace, it's the vendor's responsibility to ensure the name won't cause 295 conflicts with other names defined by libc++, both now and in the future. In particular, inline 296 namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library, 297 and so should be avoided. 298 299.. option:: LIBCXX_ABI_DEFINES:STRING 300 301 **Default**: ``""`` 302 303 A semicolon-separated list of ABI macros to persist in the site config header. 304 See ``include/__config`` for the list of ABI macros. 305 306.. option:: LIBCXX_CXX_ABI:STRING 307 308 **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``. 309 310 Select the ABI library to build libc++ against. 311 312.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 313 314 Provide additional search paths for the ABI library headers. 315 316.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 317 318 Provide the path to the ABI library that libc++ should link against. This is only 319 useful when linking against an out-of-tree ABI library. 320 321.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 322 323 **Default**: ``OFF`` 324 325 If this option is enabled, libc++ will try and link the selected ABI library 326 statically. 327 328.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 329 330 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 331 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 332 333 This option generate and installs a linker script as ``libc++.so`` which 334 links the correct ABI library. 335 336.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 337 338 **Default**: ``ON`` 339 340 Build and use the LLVM unwinder. Note: This option can only be used when 341 libc++abi is the C++ ABI library used. 342 343.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING 344 345 **Default**: ``""`` 346 347 Additional libraries libc++abi is linked to which can be provided in cache. 348 349LLVM-specific options 350--------------------- 351 352.. option:: LLVM_LIBDIR_SUFFIX:STRING 353 354 Extra suffix to append to the directory where libraries are to be 355 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 356 to install libraries to ``/usr/lib64``. 357 358.. option:: LLVM_BUILD_32_BITS:BOOL 359 360 Build 32-bits executables and libraries on 64-bits systems. This option is 361 available only on some 64-bits Unix systems. Defaults to OFF. 362 363.. option:: LLVM_LIT_ARGS:STRING 364 365 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 366 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 367 others. 368 369 370Support for Windows 371=================== 372 373Libc++ supports being built with clang-cl, but not with MSVC's cl.exe, as 374cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or 375newer (19.14) is required. 376 377Libc++ also supports being built with clang targeting MinGW environments. 378 379CMake + Visual Studio 380--------------------- 381 382Building with Visual Studio currently does not permit running tests. However, 383it is the simplest way to build. 384 385.. code-block:: batch 386 387 > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^ 388 -T "ClangCL" ^ 389 -DLLVM_ENABLE_RUNTIMES=libcxx ^ 390 -DLIBCXX_ENABLE_SHARED=YES ^ 391 -DLIBCXX_ENABLE_STATIC=NO 392 > cmake --build build 393 394CMake + ninja (MSVC) 395-------------------- 396 397Building with ninja is required for development to enable tests. 398A couple of tests require Bash to be available, and a couple dozens 399of tests require other posix tools (cp, grep and similar - LLVM's tests 400require the same). Without those tools the vast majority of tests 401can still be ran successfully. 402 403If Git for Windows is available, that can be used to provide the bash 404shell by adding the right bin directory to the path, e.g. 405``set PATH=%PATH%;C:\Program Files\Git\usr\bin``. 406 407Alternatively, one can also choose to run the whole build in a MSYS2 408shell. That can be set up e.g. by starting a Visual Studio Tools Command 409Prompt (for getting the environment variables pointing to the headers and 410import libraries), and making sure that clang-cl is available in the 411path. From there, launch an MSYS2 shell via e.g. 412``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier 413environment, allowing the MSVC headers/libraries and clang-cl to be found). 414 415In either case, then run: 416 417.. code-block:: batch 418 419 > cmake -G Ninja -S runtimes -B build ^ 420 -DCMAKE_C_COMPILER=clang-cl ^ 421 -DCMAKE_CXX_COMPILER=clang-cl ^ 422 -DLLVM_ENABLE_RUNTIMES=libcxx 423 > ninja -C build cxx 424 > ninja -C build check-cxx 425 426If you are running in an MSYS2 shell and you have installed the 427MSYS2-provided clang package (which defaults to a non-MSVC target), you 428should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing 429``x86_64`` with the architecture you're targeting) to the ``cmake`` command 430line above. This will instruct ``check-cxx`` to use the right target triple 431when invoking ``clang++``. 432 433CMake + ninja (MinGW) 434--------------------- 435 436libcxx can also be built in MinGW environments, e.g. with the MinGW 437compilers in MSYS2. This requires clang to be available (installed with 438e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja. 439 440.. code-block:: bash 441 442 > cmake -G Ninja -S runtimes -B build \ 443 -DCMAKE_C_COMPILER=clang \ 444 -DCMAKE_CXX_COMPILER=clang++ \ 445 -DLLVM_ENABLE_LLD=ON \ 446 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \ 447 -DLIBCXXABI_ENABLE_SHARED=OFF \ 448 -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON 449 > ninja -C build cxx 450 > ninja -C build check-cxx 451 452.. _`libc++abi`: http://libcxxabi.llvm.org/ 453 454 455.. _assertion-handler: 456 457Overriding the default assertion handler 458======================================== 459 460When the library wants to terminate due to a hardening assertion failure, the 461program is aborted by invoking a trap instruction (or in debug mode, by 462a special verbose termination function that prints an error message and calls 463``std::abort()``). This is done to minimize the code size impact of enabling 464hardening in the library. However, vendors can also override that mechanism at 465CMake configuration time. 466 467Under the hood, a hardening assertion will invoke the 468``_LIBCPP_ASSERTION_HANDLER`` macro upon failure. A vendor may provide a header 469that contains a custom definition of this macro and specify the path to the 470header via the ``LIBCXX_ASSERTION_HANDLER_FILE`` CMake variable. If provided, 471this header will be included by the library and replace the default 472implementation. The header must not include any standard library headers 473(directly or transitively) because doing so will almost always create a circular 474dependency. The ``_LIBCPP_ASSERTION_HANDLER(message)`` macro takes a single 475parameter that contains an error message explaining the hardening failure and 476some details about the source location that triggered it. 477 478When a hardening assertion fails, it means that the program is about to invoke 479library undefined behavior. For this reason, the custom assertion handler is 480generally expected to terminate the program. If a custom assertion handler 481decides to avoid doing so (e.g. it chooses to log and continue instead), it does 482so at its own risk -- this approach should only be used in non-production builds 483and with an understanding of potential consequences. Furthermore, the custom 484assertion handler should not throw any exceptions as it may be invoked from 485standard library functions that are marked ``noexcept`` (so throwing will result 486in ``std::terminate`` being called). 487 488 489Using Alternate ABI libraries 490============================= 491 492In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and 493more, libc++ requires what we refer to as an ABI library. Typically, that library 494implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_. 495 496By default, libc++ uses libc++abi as an ABI library. However, it is possible to use 497other ABI libraries too. 498 499Using libsupc++ on Linux 500------------------------ 501 502You will need libstdc++ in order to provide libsupc++. 503 504Figure out where the libsupc++ headers are on your system. On Ubuntu this 505is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 506 507You can also figure this out by running 508 509.. code-block:: bash 510 511 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 512 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 513 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 514 #include "..." search starts here: 515 #include <...> search starts here: 516 /usr/include/c++/4.7 517 /usr/include/c++/4.7/x86_64-linux-gnu 518 /usr/include/c++/4.7/backward 519 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 520 /usr/local/include 521 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 522 /usr/include/x86_64-linux-gnu 523 /usr/include 524 End of search list. 525 526Note that the first two entries happen to be what we are looking for. This 527may not be correct on all platforms. 528 529We can now run CMake: 530 531.. code-block:: bash 532 533 $ cmake -G Ninja -S runtimes -B build \ 534 -DLLVM_ENABLE_RUNTIMES="libcxx" \ 535 -DLIBCXX_CXX_ABI=libstdc++ \ 536 -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \ 537 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" 538 $ ninja -C build install-cxx 539 540 541You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 542above, which will cause the library to be linked to libsupc++ instead 543of libstdc++, but this is only recommended if you know that you will 544never need to link against libstdc++ in the same executable as libc++. 545GCC ships libsupc++ separately but only as a static library. If a 546program also needs to link against libstdc++, it will provide its 547own copy of libsupc++ and this can lead to subtle problems. 548 549Using libcxxrt on Linux 550------------------------ 551 552You will need to keep the source tree of `libcxxrt`_ available 553on your build machine and your copy of the libcxxrt shared library must 554be placed where your linker will find it. 555 556We can now run CMake like: 557 558.. code-block:: bash 559 560 $ cmake -G Ninja -S runtimes -B build \ 561 -DLLVM_ENABLE_RUNTIMES="libcxx" \ 562 -DLIBCXX_CXX_ABI=libcxxrt \ 563 -DLIBCXX_ENABLE_NEW_DELETE_DEFINITIONS=ON \ 564 -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \ 565 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src 566 $ ninja -C build install-cxx 567 568Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 569clang is set up to link for libc++ linked to libsupc++. To get around this 570you'll have to set up your linker yourself (or patch clang). For example, 571 572.. code-block:: bash 573 574 $ clang++ -stdlib=libc++ helloworld.cpp \ 575 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 576 577Alternately, you could just add libcxxrt to your libraries list, which in most 578situations will give the same result: 579 580.. code-block:: bash 581 582 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 583 584.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt 585