libcxx/docs/BuildingLibcxx.rst

   1 .. _BuildingLibcxx:
   2
   3 ===============
   4 Building libc++
   5 ===============
   6
   7 .. contents::
   8   :local:
   9
  10 .. _build instructions:
  11
  12 The instructions on this page are aimed at vendors who ship libc++ as part of an
  13 operating system distribution, a toolchain or similar shipping vehicles. If you
  14 are a user merely trying to use libc++ in your program, you most likely want to
  15 refer to your vendor's documentation, or to the general documentation for using
  16 libc++ :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
  25 The default build
  26 =================
  27
  28 The default way of building libc++, libc++abi and libunwind is to root the CMake
  29 invocation at ``<monorepo>/runtimes``. While those projects are under the LLVM
  30 umbrella, they are different in nature from other build tools, so it makes sense
  31 to treat them as a separate set of entities. The default build can be achieved
  32 with 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
  47 After building the various ``install-XXX`` targets, shared libraries for libc++, libc++abi and
  48 libunwind 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
  52 In the default configuration, the runtimes will be built using the compiler available by default
  53 on your system. Of course, you can change what compiler is being used with the usual CMake
  54 variables. If you wish to build the runtimes from a just-built Clang, the bootstrapping build
  55 explained below makes this task easy.
  56
  57
  58 Bootstrapping build
  59 ===================
  60
  61 It is possible to build Clang and then build the runtimes using that just-built compiler in a
  62 single CMake invocation. This is usually the correct way to build the runtimes when putting together
  63 a toolchain, or when the system compiler is not adequate to build them (too old, unsupported, etc.).
  64 To do this, use the following CMake invocation, and in particular notice how we're now rooting the
  65 CMake 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
  85 Support for Windows
  86 ===================
  87
  88 libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as
  89 cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
  90 newer (19.14) is required.
  91
  92 libcxx also supports being built with clang targeting MinGW environments.
  93
  94 CMake + Visual Studio
  95 ---------------------
  96
  97 Building with Visual Studio currently does not permit running tests. However,
  98 it 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
 109 CMake + ninja (MSVC)
 110 --------------------
 111
 112 Building with ninja is required for development to enable tests.
 113 A couple of tests require Bash to be available, and a couple dozens
 114 of tests require other posix tools (cp, grep and similar - LLVM's tests
 115 require the same). Without those tools the vast majority of tests
 116 can still be ran successfully.
 117
 118 If Git for Windows is available, that can be used to provide the bash
 119 shell by adding the right bin directory to the path, e.g.
 120 ``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
 121
 122 Alternatively, one can also choose to run the whole build in a MSYS2
 123 shell. That can be set up e.g. by starting a Visual Studio Tools Command
 124 Prompt (for getting the environment variables pointing to the headers and
 125 import libraries), and making sure that clang-cl is available in the
 126 path. From there, launch an MSYS2 shell via e.g.
 127 ``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
 128 environment, allowing the MSVC headers/libraries and clang-cl to be found).
 129
 130 In 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
 141 If you are running in an MSYS2 shell and you have installed the
 142 MSYS2-provided clang package (which defaults to a non-MSVC target), you
 143 should 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
 145 line above. This will instruct ``check-cxx`` to use the right target triple
 146 when invoking ``clang++``.
 147
 148 CMake + ninja (MinGW)
 149 ---------------------
 150
 151 libcxx can also be built in MinGW environments, e.g. with the MinGW
 152 compilers in MSYS2. This requires clang to be available (installed with
 153 e.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
 172 CMake Options
 173 =============
 174
 175 Here are some of the CMake variables that are used often, along with a
 176 brief explanation and LLVM-specific notes. For full documentation, check the
 177 CMake 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
 194 libc++ 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
 305 ABI 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**: ``OFF``
 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
 358 libc++ 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
 373 .. option:: LIBCXX_INCLUDE_TESTS:BOOL
 374
 375   **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
 376
 377   Build the libc++ tests.
 378
 379 .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
 380
 381   **Default**: ``ON``
 382
 383   Build the libc++ benchmark tests and the Google Benchmark library needed
 384   to support them.
 385
 386 .. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING
 387
 388   **Default**: ``--benchmark_min_time=0.01``
 389
 390   A semicolon list of arguments to pass when running the libc++ benchmarks using the
 391   ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time,
 392   since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to
 393   get accurate measurements.
 394
 395 .. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING
 396
 397   **Default**:: ``""``
 398
 399   **Values**:: ``libc++``, ``libstdc++``
 400
 401   Build the libc++ benchmark tests and Google Benchmark library against the
 402   specified standard library on the platform. On Linux this can be used to
 403   compare libc++ to libstdc++ by building the benchmark tests against both
 404   standard libraries.
 405
 406 .. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING
 407
 408   Use the specified GCC toolchain and standard library when building the native
 409   stdlib benchmark tests.
 410
 411
 412 libc++ ABI Feature Options
 413 --------------------------
 414
 415 The following options allow building libc++ for a different ABI version.
 416
 417 .. option:: LIBCXX_ABI_VERSION:STRING
 418
 419   **Default**: ``1``
 420
 421   Defines the target ABI version of libc++.
 422
 423 .. option:: LIBCXX_ABI_UNSTABLE:BOOL
 424
 425   **Default**: ``OFF``
 426
 427   Build the "unstable" ABI version of libc++. Includes all ABI changing features
 428   on top of the current stable version.
 429
 430 .. option:: LIBCXX_ABI_NAMESPACE:STRING
 431
 432   **Default**: ``__n`` where ``n`` is the current ABI version.
 433
 434   This option defines the name of the inline ABI versioning namespace. It can be used for building
 435   custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
 436   with other libc++ versions.
 437
 438   .. warning::
 439     When providing a custom namespace, it's the user's responsibility to ensure the name won't cause
 440     conflicts with other names defined by libc++, both now and in the future. In particular, inline
 441     namespaces of the form ``__[0-9]+`` could cause conflicts with future versions of the library,
 442     and so should be avoided.
 443
 444 .. option:: LIBCXX_ABI_DEFINES:STRING
 445
 446   **Default**: ``""``
 447
 448   A semicolon-separated list of ABI macros to persist in the site config header.
 449   See ``include/__config`` for the list of ABI macros.
 450
 451
 452 .. _LLVM-specific variables:
 453
 454 LLVM-specific options
 455 ---------------------
 456
 457 .. option:: LLVM_LIBDIR_SUFFIX:STRING
 458
 459   Extra suffix to append to the directory where libraries are to be
 460   installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
 461   to install libraries to ``/usr/lib64``.
 462
 463 .. option:: LLVM_BUILD_32_BITS:BOOL
 464
 465   Build 32-bits executables and libraries on 64-bits systems. This option is
 466   available only on some 64-bits Unix systems. Defaults to OFF.
 467
 468 .. option:: LLVM_LIT_ARGS:STRING
 469
 470   Arguments given to lit.  ``make check`` and ``make clang-test`` are affected.
 471   By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
 472   others.
 473
 474
 475 Using Alternate ABI libraries
 476 =============================
 477
 478 In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and
 479 more, libc++ requires what we refer to as an ABI library. Typically, that library
 480 implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_.
 481
 482 By default, libc++ uses libc++abi as an ABI library. However, it is possible to use
 483 other ABI libraries too.
 484
 485 Using libsupc++ on Linux
 486 ------------------------
 487
 488 You will need libstdc++ in order to provide libsupc++.
 489
 490 Figure out where the libsupc++ headers are on your system. On Ubuntu this
 491 is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``
 492
 493 You can also figure this out by running
 494
 495 .. code-block:: bash
 496
 497   $ echo | g++ -Wp,-v -x c++ - -fsyntax-only
 498   ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
 499   ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
 500   #include "..." search starts here:
 501   #include &lt;...&gt; search starts here:
 502   /usr/include/c++/4.7
 503   /usr/include/c++/4.7/x86_64-linux-gnu
 504   /usr/include/c++/4.7/backward
 505   /usr/lib/gcc/x86_64-linux-gnu/4.7/include
 506   /usr/local/include
 507   /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
 508   /usr/include/x86_64-linux-gnu
 509   /usr/include
 510   End of search list.
 511
 512 Note that the first two entries happen to be what we are looking for. This
 513 may not be correct on all platforms.
 514
 515 We can now run CMake:
 516
 517 .. code-block:: bash
 518
 519   $ cmake -G Ninja -S runtimes -B build       \
 520     -DLLVM_ENABLE_RUNTIMES="libcxx"           \
 521     -DLIBCXX_CXX_ABI=libstdc++                \
 522     -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
 523   $ ninja -C build install-cxx
 524
 525
 526 You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
 527 above, which will cause the library to be linked to libsupc++ instead
 528 of libstdc++, but this is only recommended if you know that you will
 529 never need to link against libstdc++ in the same executable as libc++.
 530 GCC ships libsupc++ separately but only as a static library.  If a
 531 program also needs to link against libstdc++, it will provide its
 532 own copy of libsupc++ and this can lead to subtle problems.
 533
 534 Using libcxxrt on Linux
 535 ------------------------
 536
 537 You will need to keep the source tree of `libcxxrt`_ available
 538 on your build machine and your copy of the libcxxrt shared library must
 539 be placed where your linker will find it.
 540
 541 We can now run CMake like:
 542
 543 .. code-block:: bash
 544
 545   $ cmake -G Ninja -S runtimes -B build                               \
 546           -DLLVM_ENABLE_RUNTIMES="libcxx"                             \
 547           -DLIBCXX_CXX_ABI=libcxxrt                                   \
 548           -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
 549   $ ninja -C build install-cxx
 550
 551 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
 552 clang is set up to link for libc++ linked to libsupc++.  To get around this
 553 you'll have to set up your linker yourself (or patch clang).  For example,
 554
 555 .. code-block:: bash
 556
 557   $ clang++ -stdlib=libc++ helloworld.cpp \
 558             -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
 559
 560 Alternately, you could just add libcxxrt to your libraries list, which in most
 561 situations will give the same result:
 562
 563 .. code-block:: bash
 564
 565   $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
 566
 567 .. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt