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 vehicules. 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 81Support for Windows 82=================== 83 84libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as 85cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or 86newer (19.14) is required. 87 88libcxx also supports being built with clang targeting MinGW environments. 89 90CMake + Visual Studio 91--------------------- 92 93Building with Visual Studio currently does not permit running tests. However, 94it is the simplest way to build. 95 96.. code-block:: batch 97 98 > cmake -G "Visual Studio 16 2019" -S runtimes -B build ^ 99 -T "ClangCL" ^ 100 -DLLVM_ENABLE_RUNTIMES=libcxx ^ 101 -DLIBCXX_ENABLE_SHARED=YES ^ 102 -DLIBCXX_ENABLE_STATIC=NO 103 > cmake --build build 104 105CMake + ninja (MSVC) 106-------------------- 107 108Building with ninja is required for development to enable tests. 109A couple of tests require Bash to be available, and a couple dozens 110of tests require other posix tools (cp, grep and similar - LLVM's tests 111require the same). Without those tools the vast majority of tests 112can still be ran successfully. 113 114If Git for Windows is available, that can be used to provide the bash 115shell by adding the right bin directory to the path, e.g. 116``set PATH=%PATH%;C:\Program Files\Git\usr\bin``. 117 118Alternatively, one can also choose to run the whole build in a MSYS2 119shell. That can be set up e.g. by starting a Visual Studio Tools Command 120Prompt (for getting the environment variables pointing to the headers and 121import libraries), and making sure that clang-cl is available in the 122path. From there, launch an MSYS2 shell via e.g. 123``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier 124environment, allowing the MSVC headers/libraries and clang-cl to be found). 125 126In either case, then run: 127 128.. code-block:: batch 129 130 > cmake -G Ninja -S runtimes -B build ^ 131 -DCMAKE_C_COMPILER=clang-cl ^ 132 -DCMAKE_CXX_COMPILER=clang-cl ^ 133 -DLLVM_ENABLE_RUNTIMES=libcxx 134 > ninja -C build cxx 135 > ninja -C build check-cxx 136 137If you are running in an MSYS2 shell and you have installed the 138MSYS2-provided clang package (which defaults to a non-MSVC target), you 139should add e.g. ``-DCMAKE_CXX_COMPILER_TARGET=x86_64-windows-msvc`` (replacing 140``x86_64`` with the architecture you're targeting) to the ``cmake`` command 141line above. This will instruct ``check-cxx`` to use the right target triple 142when invoking ``clang++``. 143 144Also note that if not building in Release mode, a failed assert in the tests 145pops up a blocking dialog box, making it hard to run a larger number of tests. 146 147CMake + ninja (MinGW) 148--------------------- 149 150libcxx can also be built in MinGW environments, e.g. with the MinGW 151compilers in MSYS2. This requires clang to be available (installed with 152e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja. 153 154.. code-block:: bash 155 156 > cmake -G Ninja -S runtimes -B build \ 157 -DCMAKE_C_COMPILER=clang \ 158 -DCMAKE_CXX_COMPILER=clang++ \ 159 -DLLVM_ENABLE_RUNTIMES=libcxx \ 160 -DLIBCXX_CXX_ABI=libstdc++ 161 > ninja -C build cxx 162 > cp /mingw64/bin/{libstdc++-6,libgcc_s_seh-1,libwinpthread-1}.dll lib 163 > ninja -C build check-cxx 164 165As this build configuration ends up depending on a couple other DLLs that 166aren't available in path while running tests, copy them into the same 167directory as the tested libc++ DLL. 168 169(Building a libc++ that depends on libstdc++ isn't necessarily a config one 170would want to deploy, but it simplifies the config for testing purposes.) 171 172.. _`libc++abi`: http://libcxxabi.llvm.org/ 173 174 175.. _CMake Options: 176 177CMake Options 178============= 179 180Here are some of the CMake variables that are used often, along with a 181brief explanation and LLVM-specific notes. For full documentation, check the 182CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 183 184**CMAKE_BUILD_TYPE**:STRING 185 Sets the build type for ``make`` based generators. Possible values are 186 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 187 the user sets the build type with the IDE settings. 188 189**CMAKE_INSTALL_PREFIX**:PATH 190 Path where LLVM will be installed if "make install" is invoked or the 191 "INSTALL" target is built. 192 193**CMAKE_CXX_COMPILER**:STRING 194 The C++ compiler to use when building and testing libc++. 195 196 197.. _libcxx-specific options: 198 199libc++ specific options 200----------------------- 201 202.. option:: LIBCXX_INSTALL_LIBRARY:BOOL 203 204 **Default**: ``ON`` 205 206 Toggle the installation of the library portion of libc++. 207 208.. option:: LIBCXX_INSTALL_HEADERS:BOOL 209 210 **Default**: ``ON`` 211 212 Toggle the installation of the libc++ headers. 213 214.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL 215 216 **Default**: ``OFF`` 217 218 Build libc++ with assertions enabled in the compiled library, and enable assertions 219 by default when building user code as well. Assertions can be turned off by users 220 by defining ``_LIBCPP_ENABLE_ASSERTIONS=0``. For details, see 221 :ref:`the documentation <assertions-mode>`. 222 223.. option:: LIBCXX_ENABLE_SHARED:BOOL 224 225 **Default**: ``ON`` 226 227 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or 228 `LIBCXX_ENABLE_STATIC` has to be enabled. 229 230.. option:: LIBCXX_ENABLE_STATIC:BOOL 231 232 **Default**: ``ON`` 233 234 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or 235 `LIBCXX_ENABLE_STATIC` has to be enabled. 236 237.. option:: LIBCXX_LIBDIR_SUFFIX:STRING 238 239 Extra suffix to append to the directory where libraries are to be installed. 240 This option overrides `LLVM_LIBDIR_SUFFIX`. 241 242.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL 243 244 **Default**: ``OFF`` 245 246 Do not export any symbols from the static libc++ library. 247 This is useful when the static libc++ library is being linked into shared 248 libraries that may be used in with other shared libraries that use different 249 C++ library. We want to avoid exporting any libc++ symbols in that case. 250 251.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 252 253 **Default**: ``ON`` except on Windows when using MSVC. 254 255 This option can be used to enable or disable the filesystem components on 256 platforms that may not support them. For example on Windows when using MSVC. 257 258.. option:: LIBCXX_ENABLE_WIDE_CHARACTERS:BOOL 259 260 **Default**: ``ON`` 261 262 This option can be used to disable support for ``wchar_t`` in the library. It also 263 allows the library to work on top of a C Standard Library that does not provide 264 support for ``wchar_t``. This is especially useful in embedded settings where 265 C Standard Libraries don't always provide all the usual bells and whistles. 266 267.. option:: LIBCXX_INSTALL_LIBRARY_DIR:PATH 268 269 **Default**: ``lib${LIBCXX_LIBDIR_SUFFIX}`` 270 271 Path where built libc++ libraries should be installed. If a relative path, 272 relative to ``CMAKE_INSTALL_PREFIX``. 273 274.. option:: LIBCXX_INSTALL_INCLUDE_DIR:PATH 275 276 **Default**: ``include/c++/v1`` 277 278 Path where target-agnostic libc++ headers should be installed. If a relative 279 path, relative to ``CMAKE_INSTALL_PREFIX``. 280 281.. option:: LIBCXX_INSTALL_INCLUDE_TARGET_DIR:PATH 282 283 **Default**: ``include/c++/v1`` or 284 ``include/${LLVM_DEFAULT_TARGET_TRIPLE}/c++/v1`` 285 286 Path where target-specific libc++ headers should be installed. If a relative 287 path, relative to ``CMAKE_INSTALL_PREFIX``. 288 289.. option:: LIBCXX_SHARED_OUTPUT_NAME:STRING 290 291 **Default**: ``c++`` 292 293 Output name for the shared libc++ runtime library. 294 295.. option:: LIBCXX_ADDITIONAL_COMPILE_FLAGS:STRING 296 297 **Default**: ``""`` 298 299 Additional Compile only flags which can be provided in cache. 300 301.. option:: LIBCXX_ADDITIONAL_LIBRARIES:STRING 302 303 **Default**: ``""`` 304 305 Additional libraries libc++ is linked to which can be provided in cache. 306 307 308.. _ABI Library Specific Options: 309 310ABI Library Specific Options 311---------------------------- 312 313.. option:: LIBCXX_CXX_ABI:STRING 314 315 **Values**: ``none``, ``libcxxabi``, ``system-libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``, ``vcruntime``. 316 317 Select the ABI library to build libc++ against. 318 319.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 320 321 Provide additional search paths for the ABI library headers. 322 323.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 324 325 Provide the path to the ABI library that libc++ should link against. This is only 326 useful when linking against an out-of-tree ABI library. 327 328.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 329 330 **Default**: ``OFF`` 331 332 If this option is enabled, libc++ will try and link the selected ABI library 333 statically. 334 335.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 336 337 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 338 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 339 340 This option generate and installs a linker script as ``libc++.so`` which 341 links the correct ABI library. 342 343.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 344 345 **Default**: ``OFF`` 346 347 Build and use the LLVM unwinder. Note: This option can only be used when 348 libc++abi is the C++ ABI library used. 349 350.. option:: LIBCXXABI_ADDITIONAL_COMPILE_FLAGS:STRING 351 352 **Default**: ``""`` 353 354 Additional Compile only flags which can be provided in cache. 355 356.. option:: LIBCXXABI_ADDITIONAL_LIBRARIES:STRING 357 358 **Default**: ``""`` 359 360 Additional libraries libc++abi is linked to which can be provided in cache. 361 362 363libc++ Feature Options 364---------------------- 365 366.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 367 368 **Default**: ``ON`` 369 370 Build libc++ with exception support. 371 372.. option:: LIBCXX_ENABLE_RTTI:BOOL 373 374 **Default**: ``ON`` 375 376 Build libc++ with run time type information. 377 378.. option:: LIBCXX_INCLUDE_TESTS:BOOL 379 380 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``) 381 382 Build the libc++ tests. 383 384.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 385 386 **Default**: ``ON`` 387 388 Build the libc++ benchmark tests and the Google Benchmark library needed 389 to support them. 390 391.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING 392 393 **Default**: ``--benchmark_min_time=0.01`` 394 395 A semicolon list of arguments to pass when running the libc++ benchmarks using the 396 ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time, 397 since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to 398 get accurate measurements. 399 400.. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING 401 402 **Default**:: ``""`` 403 404 **Values**:: ``libc++``, ``libstdc++`` 405 406 Build the libc++ benchmark tests and Google Benchmark library against the 407 specified standard library on the platform. On Linux this can be used to 408 compare libc++ to libstdc++ by building the benchmark tests against both 409 standard libraries. 410 411.. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING 412 413 Use the specified GCC toolchain and standard library when building the native 414 stdlib benchmark tests. 415 416 417libc++ ABI Feature Options 418-------------------------- 419 420The following options allow building libc++ for a different ABI version. 421 422.. option:: LIBCXX_ABI_VERSION:STRING 423 424 **Default**: ``1`` 425 426 Defines the target ABI version of libc++. 427 428.. option:: LIBCXX_ABI_UNSTABLE:BOOL 429 430 **Default**: ``OFF`` 431 432 Build the "unstable" ABI version of libc++. Includes all ABI changing features 433 on top of the current stable version. 434 435.. option:: LIBCXX_ABI_NAMESPACE:STRING 436 437 **Default**: ``__n`` where ``n`` is the current ABI version. 438 439 This option defines the name of the inline ABI versioning namespace. It can be used for building 440 custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues 441 with other libc++ versions. 442 443 .. warning:: 444 When providing a custom namespace, it's the user's responsibility to ensure the name won't cause 445 conflicts with other names defined by libc++, both now and in the future. In particular, inline 446 namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library, 447 and so should be avoided. 448 449.. option:: LIBCXX_ABI_DEFINES:STRING 450 451 **Default**: ``""`` 452 453 A semicolon-separated list of ABI macros to persist in the site config header. 454 See ``include/__config`` for the list of ABI macros. 455 456 457.. _LLVM-specific variables: 458 459LLVM-specific options 460--------------------- 461 462.. option:: LLVM_LIBDIR_SUFFIX:STRING 463 464 Extra suffix to append to the directory where libraries are to be 465 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 466 to install libraries to ``/usr/lib64``. 467 468.. option:: LLVM_BUILD_32_BITS:BOOL 469 470 Build 32-bits executables and libraries on 64-bits systems. This option is 471 available only on some 64-bits Unix systems. Defaults to OFF. 472 473.. option:: LLVM_LIT_ARGS:STRING 474 475 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 476 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 477 others. 478 479 480Using Alternate ABI libraries 481============================= 482 483In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and 484more, libc++ requires what we refer to as an ABI library. Typically, that library 485implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_. 486 487By default, libc++ uses libc++abi as an ABI library. However, it is possible to use 488other ABI libraries too. 489 490Using libsupc++ on Linux 491------------------------ 492 493You will need libstdc++ in order to provide libsupc++. 494 495Figure out where the libsupc++ headers are on your system. On Ubuntu this 496is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 497 498You can also figure this out by running 499 500.. code-block:: bash 501 502 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 503 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 504 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 505 #include "..." search starts here: 506 #include <...> search starts here: 507 /usr/include/c++/4.7 508 /usr/include/c++/4.7/x86_64-linux-gnu 509 /usr/include/c++/4.7/backward 510 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 511 /usr/local/include 512 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 513 /usr/include/x86_64-linux-gnu 514 /usr/include 515 End of search list. 516 517Note that the first two entries happen to be what we are looking for. This 518may not be correct on all platforms. 519 520We can now run CMake: 521 522.. code-block:: bash 523 524 $ cmake -G Ninja -S runtimes -B build \ 525 -DLLVM_ENABLE_RUNTIMES="libcxx" \ 526 -DLIBCXX_CXX_ABI=libstdc++ \ 527 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" 528 $ ninja -C build install-cxx 529 530 531You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 532above, which will cause the library to be linked to libsupc++ instead 533of libstdc++, but this is only recommended if you know that you will 534never need to link against libstdc++ in the same executable as libc++. 535GCC ships libsupc++ separately but only as a static library. If a 536program also needs to link against libstdc++, it will provide its 537own copy of libsupc++ and this can lead to subtle problems. 538 539Using libcxxrt on Linux 540------------------------ 541 542You will need to keep the source tree of `libcxxrt`_ available 543on your build machine and your copy of the libcxxrt shared library must 544be placed where your linker will find it. 545 546We can now run CMake like: 547 548.. code-block:: bash 549 550 $ cmake -G Ninja -S runtimes -B build \ 551 -DLLVM_ENABLE_RUNTIMES="libcxx" \ 552 -DLIBCXX_CXX_ABI=libcxxrt \ 553 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src 554 $ ninja -C build install-cxx 555 556Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 557clang is set up to link for libc++ linked to libsupc++. To get around this 558you'll have to set up your linker yourself (or patch clang). For example, 559 560.. code-block:: bash 561 562 $ clang++ -stdlib=libc++ helloworld.cpp \ 563 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 564 565Alternately, you could just add libcxxrt to your libraries list, which in most 566situations will give the same result: 567 568.. code-block:: bash 569 570 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 571 572.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt 573