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