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