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