598 lines · plain
1.. _VendorDocumentation:2 3====================4Vendor Documentation5====================6 7.. contents::8 :local:9 10The instructions on this page are aimed at vendors who ship libc++ as part of an11operating system distribution, a toolchain or similar shipping vehicles. If you12are a user merely trying to use libc++ in your program, you most likely want to13refer to your vendor's documentation, or to the general user documentation14:ref:`here <user-documentation>`.15 16.. warning::17 If your operating system already provides libc++, it is important to be careful18 not to replace it. Replacing your system's libc++ installation could render it19 non-functional. Use the CMake option ``CMAKE_INSTALL_PREFIX`` to select a safe20 place to install libc++.21 22 23The default build24=================25 26The default way of building libc++, libc++abi and libunwind is to root the CMake27invocation at ``<monorepo>/runtimes``. While those projects are under the LLVM28umbrella, they are different in nature from other build tools, so it makes sense29to treat them as a separate set of entities. The default build can be achieved30with the following CMake invocation:31 32.. code-block:: bash33 34 $ git clone https://github.com/llvm/llvm-project.git35 $ cd llvm-project36 $ mkdir build37 $ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" # Configure38 $ ninja -C build cxx cxxabi unwind # Build39 $ ninja -C build check-cxx check-cxxabi check-unwind # Test40 $ ninja -C build install-cxx install-cxxabi install-unwind # Install41 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 and46libunwind should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and headers in47``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See the instructions below for information on how48to use this libc++ over the default one.49 50In the default configuration, the runtimes will be built using the compiler available by default51on your system. Of course, you can change what compiler is being used with the usual CMake52variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build53explained 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 and59to override it with custom paths. With Clang, this can be done with:60 61.. code-block:: bash62 63 $ clang++ -nostdinc++ -isystem <install>/include/c++/v1 \64 -nostdlib++ -L <install>/lib -lc++ \65 -Wl,-rpath,<install>/lib \66 test.cpp67 68The option ``-Wl,-rpath,<install>/lib`` adds a runtime library search path, which causes the system's69dynamic linker to look for libc++ in ``<install>/lib`` whenever the program is loaded.70 71 72The Bootstrapping build73=======================74 75It is possible to build Clang and then build the runtimes using that just-built compiler in a76single CMake invocation. This is usually the correct way to build the runtimes when putting together77a 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 the79CMake invocation at ``<monorepo>/llvm``:80 81.. code-block:: bash82 83 $ mkdir build84 $ cmake -G Ninja -S llvm -B build \85 -DCMAKE_BUILD_TYPE=RelWithDebInfo \86 -DLLVM_ENABLE_PROJECTS="clang" \ # Configure87 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind;compiler-rt" \88 -DLLVM_RUNTIME_TARGETS="<target-triple>"89 $ ninja -C build runtimes # Build90 $ ninja -C build check-runtimes # Test91 $ ninja -C build install-runtimes # Install92 93.. note::94 - This type of build is also commonly called a "Runtimes build", but we would like to move95 away from that terminology, which is too confusing.96 97 - Adding the `--fresh` flag to the top-level cmake invocation in a bootstrapping build *will not*98 freshen the cmake cache of any of the enabled runtimes.99 100 101.. _Vendor Configuration Options:102 103Vendor Configuration Options104============================105 106This section documents configuration options that can be used by vendors when building the library.107These options provide a great deal of flexibility to customize libc++, such as selecting the ABI in108use, whether some features are provided, etc.109 110.. warning::111 Many of these CMake options are tied to configuration macros with a corresponding name in the source112 code. However, these configuration macros are not intended to be customized by users directly, since113 many of them require the library to be built with a matching configuration. If you don't build libc++114 yourself, you should not use the options documented here.115 116General purpose options117-----------------------118 119.. option:: LIBCXX_INSTALL_LIBRARY:BOOL120 121 **Default**: ``ON``122 123 Toggle the installation of the library portion of libc++.124 125.. option:: LIBCXX_INSTALL_HEADERS:BOOL126 127 **Default**: ``ON``128 129 Toggle the installation of the libc++ headers.130 131.. option:: LIBCXX_INSTALL_MODULES:BOOL132 133 **Default**: ``ON``134 135 Toggle the installation of the experimental libc++ module sources.136 137.. option:: LIBCXX_ENABLE_SHARED:BOOL138 139 **Default**: ``ON``140 141 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or142 `LIBCXX_ENABLE_STATIC` has to be enabled.143 144.. option:: LIBCXX_ENABLE_STATIC:BOOL145 146 **Default**: ``ON``147 148 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or149 `LIBCXX_ENABLE_STATIC` has to be enabled.150 151.. option:: LIBCXX_LIBDIR_SUFFIX:STRING152 153 Extra suffix to append to the directory where libraries are to be installed.154 This option overrides `LLVM_LIBDIR_SUFFIX`.155 156.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL157 158 **Default**: ``OFF``159 160 Do not export any symbols from the static libc++ library.161 This is useful when the static libc++ library is being linked into shared162 libraries that may be used in with other shared libraries that use different163 C++ library. We want to avoid exporting any libc++ symbols in that case.164 165.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL166 167 **Default**: ``ON``168 169 This option can be used to enable or disable the filesystem components on170 platforms that may not support them.171 172.. option:: LIBCXX_ENABLE_WIDE_CHARACTERS:BOOL173 174 **Default**: ``ON``175 176 This option can be used to disable support for ``wchar_t`` in the library. It also177 allows the library to work on top of a C Standard Library that does not provide178 support for ``wchar_t``. This is especially useful in embedded settings where179 C Standard Libraries don't always provide all the usual bells and whistles.180 181.. option:: LIBCXX_ENABLE_TIME_ZONE_DATABASE:BOOL182 183 **Default**: ``ON``184 185 Whether to include support for time zones in the library. Disabling186 time zone support can be useful when porting to platforms that don't187 ship the IANA time zone database. When time zones are not supported,188 time zone support in <chrono> will be disabled.189 190.. option:: LIBCXX_INSTALL_LIBRARY_DIR:PATH191 192 **Default**: ``lib${LIBCXX_LIBDIR_SUFFIX}``193 194 Path where built libc++ libraries should be installed. If a relative path,195 relative to ``CMAKE_INSTALL_PREFIX``.196 197.. option:: LIBCXX_INSTALL_INCLUDE_DIR:PATH198 199 **Default**: ``include/c++/v1``200 201 Path where target-agnostic libc++ headers should be installed. If a relative202 path, relative to ``CMAKE_INSTALL_PREFIX``.203 204.. option:: LIBCXX_INSTALL_INCLUDE_TARGET_DIR:PATH205 206 **Default**: ``include/c++/v1`` or207 ``include/${LLVM_DEFAULT_TARGET_TRIPLE}/c++/v1``208 209 Path where target-specific libc++ headers should be installed. If a relative210 path, relative to ``CMAKE_INSTALL_PREFIX``.211 212.. option:: LIBCXX_SHARED_OUTPUT_NAME:STRING213 214 **Default**: ``c++``215 216 Output name for the shared libc++ runtime library.217 218.. option:: {LIBCXX,LIBCXXABI,LIBUNWIND}_ADDITIONAL_COMPILE_FLAGS:STRING219 220 **Default**: ``""``221 222 Additional compile flags to use when building the runtimes. This should be a CMake ``;``-delimited list of individual223 compiler options to use. For options that must be passed as-is to the compiler without deduplication (e.g.224 ``-Xclang -foo`` option groups), consider using ``SHELL:`` as `documented here <https://cmake.org/cmake/help/latest/command/add_compile_options.html#option-de-duplication>`_.225 226.. option:: LIBCXX_ADDITIONAL_LIBRARIES:STRING227 228 **Default**: ``""``229 230 Additional libraries libc++ is linked to which can be provided in cache.231 232.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL233 234 **Default**: ``ON``235 236 Build libc++ with exception support.237 238.. option:: LIBCXX_ENABLE_RTTI:BOOL239 240 **Default**: ``ON``241 242 Build libc++ with run time type information.243 This option may only be set to OFF when LIBCXX_ENABLE_EXCEPTIONS=OFF.244 245.. option:: LIBCXX_INCLUDE_TESTS:BOOL246 247 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)248 249 Build the libc++ test suite, which includes various types of tests like conformance250 tests, vendor-specific tests and benchmarks.251 252.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL253 254 **Default**: ``ON``255 256 Build the libc++ benchmark tests and the Google Benchmark library needed257 to support them.258 259.. option:: LIBCXX_ASSERTION_HANDLER_FILE:PATH260 261 **Default**:: ``"${CMAKE_CURRENT_SOURCE_DIR}/vendor/llvm/default_assertion_handler.in"``262 263 Specify the path to a header that contains a custom implementation of the264 assertion handler that gets invoked when a hardening assertion fails. If265 provided, this header will be included by the library, replacing the266 default assertion handler. If this is specified as a relative path, it267 is assumed to be relative to ``<monorepo>/libcxx``.268 269ABI Specific Options270--------------------271 272The following options allow building libc++ for a different ABI version.273 274.. option:: LIBCXX_ABI_VERSION:STRING275 276 **Default**: ``1``277 278 Defines the target ABI version of libc++.279 280.. option:: LIBCXX_ABI_UNSTABLE:BOOL281 282 **Default**: ``OFF``283 284 Build the "unstable" ABI version of libc++. Includes all ABI changing features285 on top of the current stable version.286 287.. option:: LIBCXX_ABI_NAMESPACE:STRING288 289 **Default**: ``__n`` where ``n`` is the current ABI version.290 291 This option defines the name of the inline ABI versioning namespace. It can be used for building292 custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues293 with other libc++ versions.294 295 .. warning::296 When providing a custom namespace, it's the vendor's responsibility to ensure the name won't cause297 conflicts with other names defined by libc++, both now and in the future. In particular, inline298 namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library,299 and so should be avoided.300 301.. option:: LIBCXX_ABI_DEFINES:STRING302 303 **Default**: ``""``304 305 A semicolon-separated list of ABI macros to persist in the site config header.306 See ``include/__config`` for the list of ABI macros.307 308.. option:: LIBCXX_CXX_ABI:STRING309 310 **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``.311 312 Select the ABI library to build libc++ against.313 314.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS315 316 Provide additional search paths for the ABI library headers.317 318.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH319 320 Provide the path to the ABI library that libc++ should link against. This is only321 useful when linking against an out-of-tree ABI library.322 323.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL324 325 **Default**: ``OFF``326 327 If this option is enabled, libc++ will try and link the selected ABI library328 statically.329 330.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL331 332 **Default**: ``ON`` by default on UNIX platforms other than Apple unless333 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.334 335 This option generate and installs a linker script as ``libc++.so`` which336 links the correct ABI library.337 338.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL339 340 **Default**: ``ON``341 342 Build and use the LLVM unwinder. Note: This option can only be used when343 libc++abi is the C++ ABI library used.344 345.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING346 347 **Default**: ``""``348 349 Additional libraries libc++abi is linked to which can be provided in cache.350 351LLVM-specific options352---------------------353 354.. option:: LLVM_LIBDIR_SUFFIX:STRING355 356 Extra suffix to append to the directory where libraries are to be357 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``358 to install libraries to ``/usr/lib64``.359 360.. option:: LLVM_BUILD_32_BITS:BOOL361 362 Build 32-bits executables and libraries on 64-bits systems. This option is363 available only on some 64-bits Unix systems. Defaults to OFF.364 365.. option:: LLVM_LIT_ARGS:STRING366 367 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.368 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on369 others.370 371 372Support for Windows373===================374 375Libc++ supports being built with clang-cl, but not with MSVC's cl.exe, as376cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or377newer (19.14) is required.378 379Libc++ also supports being built with clang targeting MinGW environments.380 381Libc++ supports Windows 7 or newer. However, the minimum runtime version382of the build is determined by the ``_WIN32_WINNT`` define, which in many383SDKs defaults to the latest version. To build a version that runs on an384older version, define e.g. ``_WIN32_WINNT=0x601`` while building libc++,385to target Windows 7.386 387CMake + Visual Studio388---------------------389 390Building with Visual Studio currently does not permit running tests. However,391it is the simplest way to build.392 393.. code-block:: batch394 395 > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^396 -T "ClangCL" ^397 -DLLVM_ENABLE_RUNTIMES=libcxx ^398 -DLIBCXX_ENABLE_SHARED=YES ^399 -DLIBCXX_ENABLE_STATIC=NO400 > cmake --build build401 402CMake + ninja (MSVC)403--------------------404 405Building with ninja is required for development to enable tests.406A couple of tests require Bash to be available, and a couple dozens407of tests require other posix tools (cp, grep and similar - LLVM's tests408require the same). Without those tools the vast majority of tests409can still be ran successfully.410 411If Git for Windows is available, that can be used to provide the bash412shell by adding the right bin directory to the path, e.g.413``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.414 415Alternatively, one can also choose to run the whole build in a MSYS2416shell. That can be set up e.g. by starting a Visual Studio Tools Command417Prompt (for getting the environment variables pointing to the headers and418import libraries), and making sure that clang-cl is available in the419path. From there, launch an MSYS2 shell via e.g.420``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier421environment, allowing the MSVC headers/libraries and clang-cl to be found).422 423In either case, then run:424 425.. code-block:: batch426 427 > cmake -G Ninja -S runtimes -B build ^428 -DCMAKE_C_COMPILER=clang-cl ^429 -DCMAKE_CXX_COMPILER=clang-cl ^430 -DLLVM_ENABLE_RUNTIMES=libcxx431 > ninja -C build cxx432 > ninja -C build check-cxx433 434If you are running in an MSYS2 shell and you have installed the435MSYS2-provided clang package (which defaults to a non-MSVC target), you436should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing437``x86_64`` with the architecture you're targeting) to the ``cmake`` command438line above. This will instruct ``check-cxx`` to use the right target triple439when invoking ``clang++``.440 441CMake + ninja (MinGW)442---------------------443 444libcxx can also be built in MinGW environments, e.g. with the MinGW445compilers in MSYS2. This requires clang to be available (installed with446e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.447 448.. code-block:: bash449 450 > cmake -G Ninja -S runtimes -B build \451 -DCMAKE_C_COMPILER=clang \452 -DCMAKE_CXX_COMPILER=clang++ \453 -DLLVM_ENABLE_LLD=ON \454 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" \455 -DLIBCXXABI_ENABLE_SHARED=OFF \456 -DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON457 > ninja -C build cxx458 > ninja -C build check-cxx459 460.. _`libc++abi`: http://libcxxabi.llvm.org/461 462 463.. _assertion-handler:464 465Overriding the default assertion handler466========================================467 468When the library wants to terminate due to a hardening assertion failure, the469program is aborted by invoking a trap instruction (or in debug mode, by470a special verbose termination function that prints an error message and calls471``std::abort()``). This is done to minimize the code size impact of enabling472hardening in the library. However, vendors can also override that mechanism at473CMake configuration time.474 475Under the hood, a hardening assertion will invoke the476``_LIBCPP_ASSERTION_HANDLER`` macro upon failure. A vendor may provide a header477that contains a custom definition of this macro and specify the path to the478header via the ``LIBCXX_ASSERTION_HANDLER_FILE`` CMake variable. If provided,479this header will be included by the library and replace the default480implementation. The header must not include any standard library headers481(directly or transitively) because doing so will almost always create a circular482dependency. The ``_LIBCPP_ASSERTION_HANDLER(message)`` macro takes a single483parameter that contains an error message explaining the hardening failure and484some details about the source location that triggered it.485 486When a hardening assertion fails, it means that the program is about to invoke487library undefined behavior. For this reason, the custom assertion handler is488generally expected to terminate the program. If a custom assertion handler489decides to avoid doing so (e.g. it chooses to log and continue instead), it does490so at its own risk -- this approach should only be used in non-production builds491and with an understanding of potential consequences. Furthermore, the custom492assertion handler should not throw any exceptions as it may be invoked from493standard library functions that are marked ``noexcept`` (so throwing will result494in ``std::terminate`` being called).495 496 497Using Alternate ABI libraries498=============================499 500In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and501more, libc++ requires what we refer to as an ABI library. Typically, that library502implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_.503 504By default, libc++ uses libc++abi as an ABI library. However, it is possible to use505other ABI libraries too.506 507Using libsupc++ on Linux508------------------------509 510You will need libstdc++ in order to provide libsupc++.511 512Figure out where the libsupc++ headers are on your system. On Ubuntu this513is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``514 515You can also figure this out by running516 517.. code-block:: bash518 519 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only520 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"521 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"522 #include "..." search starts here:523 #include <...> search starts here:524 /usr/include/c++/4.7525 /usr/include/c++/4.7/x86_64-linux-gnu526 /usr/include/c++/4.7/backward527 /usr/lib/gcc/x86_64-linux-gnu/4.7/include528 /usr/local/include529 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed530 /usr/include/x86_64-linux-gnu531 /usr/include532 End of search list.533 534Note that the first two entries happen to be what we are looking for. This535may not be correct on all platforms.536 537We can now run CMake:538 539.. code-block:: bash540 541 $ cmake -G Ninja -S runtimes -B build \542 -DLLVM_ENABLE_RUNTIMES="libcxx" \543 -DLIBCXX_CXX_ABI=libstdc++ \544 -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \545 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"546 $ ninja -C build install-cxx547 548 549You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``550above, which will cause the library to be linked to libsupc++ instead551of libstdc++, but this is only recommended if you know that you will552never need to link against libstdc++ in the same executable as libc++.553GCC ships libsupc++ separately but only as a static library. If a554program also needs to link against libstdc++, it will provide its555own copy of libsupc++ and this can lead to subtle problems.556 557Using libcxxrt on Linux558------------------------559 560You will need to keep the source tree of `libcxxrt`_ available561on your build machine and your copy of the libcxxrt shared library must562be placed where your linker will find it.563 564We can now run CMake like:565 566.. code-block:: bash567 568 $ cmake -G Ninja -S runtimes -B build \569 -DLLVM_ENABLE_RUNTIMES="libcxx" \570 -DLIBCXX_CXX_ABI=libcxxrt \571 -DLIBCXX_ENABLE_NEW_DELETE_DEFINITIONS=ON \572 -DLIBCXXABI_USE_LLVM_UNWINDER=OFF \573 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src574 $ ninja -C build install-cxx575 576Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as577clang is set up to link for libc++ linked to libsupc++. To get around this578you'll have to set up your linker yourself (or patch clang). For example,579 580.. code-block:: bash581 582 $ clang++ -stdlib=libc++ helloworld.cpp \583 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc584 585Alternately, you could just add libcxxrt to your libraries list, which in most586situations will give the same result:587 588.. code-block:: bash589 590 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt591 592.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt593 594libc++'s ABI guarantees595=======================596 597Libc++ provides several ABI guarantees, which are documented :ref:`here <ABIGuarantees>`.598