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 72Experimental Support for Windows 73-------------------------------- 74 75The Windows support requires building with clang-cl as cl does not support one 76required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is 77required. In the case of clang-cl, we need to specify the "MS Compatibility 78Version" as it defaults to 2014 (18.00). 79 80CMake + Visual Studio 81~~~~~~~~~~~~~~~~~~~~~ 82 83Building with Visual Studio currently does not permit running tests. However, 84it is the simplest way to build. 85 86.. code-block:: batch 87 88 > cmake -G "Visual Studio 14 2015" ^ 89 -T "LLVM-vs2014" ^ 90 -DLIBCXX_ENABLE_SHARED=YES ^ 91 -DLIBCXX_ENABLE_STATIC=NO ^ 92 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ 93 \path\to\libcxx 94 > cmake --build . 95 96CMake + ninja 97~~~~~~~~~~~~~ 98 99Building with ninja is required for development to enable tests. 100Unfortunately, doing so requires additional configuration as we cannot 101just specify a toolset. 102 103.. code-block:: batch 104 105 > cmake -G Ninja ^ 106 -DCMAKE_MAKE_PROGRAM=/path/to/ninja ^ 107 -DCMAKE_SYSTEM_NAME=Windows ^ 108 -DCMAKE_C_COMPILER=clang-cl ^ 109 -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ 110 -DCMAKE_CXX_COMPILER=clang-cl ^ 111 -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ 112 -DLLVM_PATH=/path/to/llvm/tree ^ 113 -DLIBCXX_ENABLE_SHARED=YES ^ 114 -DLIBCXX_ENABLE_STATIC=NO ^ 115 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ 116 \path\to\libcxx 117 > /path/to/ninja cxx 118 > /path/to/ninja check-cxx 119 120Note that the paths specified with backward slashes must use the `\\` as the 121directory separator as clang-cl may otherwise parse the path as an argument. 122 123.. _`libc++abi`: http://libcxxabi.llvm.org/ 124 125 126.. _CMake Options: 127 128CMake Options 129============= 130 131Here are some of the CMake variables that are used often, along with a 132brief explanation and LLVM-specific notes. For full documentation, check the 133CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 134 135**CMAKE_BUILD_TYPE**:STRING 136 Sets the build type for ``make`` based generators. Possible values are 137 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 138 the user sets the build type with the IDE settings. 139 140**CMAKE_INSTALL_PREFIX**:PATH 141 Path where LLVM will be installed if "make install" is invoked or the 142 "INSTALL" target is built. 143 144**CMAKE_CXX_COMPILER**:STRING 145 The C++ compiler to use when building and testing libc++. 146 147 148.. _libcxx-specific options: 149 150libc++ specific options 151----------------------- 152 153.. option:: LIBCXX_INSTALL_LIBRARY:BOOL 154 155 **Default**: ``ON`` 156 157 Toggle the installation of the library portion of libc++. 158 159.. option:: LIBCXX_INSTALL_HEADERS:BOOL 160 161 **Default**: ``ON`` 162 163 Toggle the installation of the libc++ headers. 164 165.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL 166 167 **Default**: ``OFF`` 168 169 Build libc++ with assertions enabled. 170 171.. option:: LIBCXX_BUILD_32_BITS:BOOL 172 173 **Default**: ``OFF`` 174 175 Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`. 176 177.. option:: LIBCXX_ENABLE_SHARED:BOOL 178 179 **Default**: ``ON`` 180 181 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or 182 `LIBCXX_ENABLE_STATIC` has to be enabled. 183 184.. option:: LIBCXX_ENABLE_STATIC:BOOL 185 186 **Default**: ``ON`` 187 188 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or 189 `LIBCXX_ENABLE_STATIC` has to be enabled. 190 191.. option:: LIBCXX_LIBDIR_SUFFIX:STRING 192 193 Extra suffix to append to the directory where libraries are to be installed. 194 This option overrides `LLVM_LIBDIR_SUFFIX`. 195 196.. option:: LIBCXX_INSTALL_PREFIX:STRING 197 198 **Default**: ``""`` 199 200 Define libc++ destination prefix. 201 202.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL 203 204 **Default**: ``OFF`` 205 206 Do not export any symbols from the static libc++ library. 207 This is useful when the static libc++ library is being linked into shared 208 libraries that may be used in with other shared libraries that use different 209 C++ library. We want to avoid exporting any libc++ symbols in that case. 210 211.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 212 213 **Default**: ``ON`` except on Windows. 214 215 This option can be used to enable or disable the filesystem components on 216 platforms that may not support them. For example on Windows. 217 218.. _libc++experimental options: 219 220libc++experimental Specific Options 221------------------------------------ 222 223.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL 224 225 **Default**: ``ON`` 226 227 Build and test libc++experimental.a. 228 229.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL 230 231 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` 232 233 Install libc++experimental.a alongside libc++. 234 235 236.. _ABI Library Specific Options: 237 238ABI Library Specific Options 239---------------------------- 240 241.. option:: LIBCXX_CXX_ABI:STRING 242 243 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. 244 245 Select the ABI library to build libc++ against. 246 247.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 248 249 Provide additional search paths for the ABI library headers. 250 251.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 252 253 Provide the path to the ABI library that libc++ should link against. 254 255.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 256 257 **Default**: ``OFF`` 258 259 If this option is enabled, libc++ will try and link the selected ABI library 260 statically. 261 262.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 263 264 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 265 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 266 267 This option generate and installs a linker script as ``libc++.so`` which 268 links the correct ABI library. 269 270.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 271 272 **Default**: ``OFF`` 273 274 Build and use the LLVM unwinder. Note: This option can only be used when 275 libc++abi is the C++ ABI library used. 276 277 278libc++ Feature Options 279---------------------- 280 281.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 282 283 **Default**: ``ON`` 284 285 Build libc++ with exception support. 286 287.. option:: LIBCXX_ENABLE_RTTI:BOOL 288 289 **Default**: ``ON`` 290 291 Build libc++ with run time type information. 292 293.. option:: LIBCXX_INCLUDE_TESTS:BOOL 294 295 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_DIR``) 296 297 Build the libc++ tests. 298 299.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 300 301 **Default**: ``ON`` 302 303 Build the libc++ benchmark tests and the Google Benchmark library needed 304 to support them. 305 306.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING 307 308 **Default**: ``--benchmark_min_time=0.01`` 309 310 A semicolon list of arguments to pass when running the libc++ benchmarks using the 311 ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time, 312 since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to 313 get accurate measurements. 314 315.. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING 316 317 **Default**:: ``""`` 318 319 **Values**:: ``libc++``, ``libstdc++`` 320 321 Build the libc++ benchmark tests and Google Benchmark library against the 322 specified standard library on the platform. On Linux this can be used to 323 compare libc++ to libstdc++ by building the benchmark tests against both 324 standard libraries. 325 326.. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING 327 328 Use the specified GCC toolchain and standard library when building the native 329 stdlib benchmark tests. 330 331.. option:: LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL 332 333 **Default**: ``OFF`` 334 335 Pick the default for whether to constrain ABI-unstable symbols to 336 each individual translation unit. This setting controls whether 337 `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined by default -- 338 see the documentation of that macro for details. 339 340 341libc++ ABI Feature Options 342-------------------------- 343 344The following options allow building libc++ for a different ABI version. 345 346.. option:: LIBCXX_ABI_VERSION:STRING 347 348 **Default**: ``1`` 349 350 Defines the target ABI version of libc++. 351 352.. option:: LIBCXX_ABI_UNSTABLE:BOOL 353 354 **Default**: ``OFF`` 355 356 Build the "unstable" ABI version of libc++. Includes all ABI changing features 357 on top of the current stable version. 358 359.. option:: LIBCXX_ABI_NAMESPACE:STRING 360 361 **Default**: ``__n`` where ``n`` is the current ABI version. 362 363 This option defines the name of the inline ABI versioning namespace. It can be used for building 364 custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues 365 with other libc++ versions. 366 367 .. warning:: 368 When providing a custom namespace, it's the users responsibility to ensure the name won't cause 369 conflicts with other names defined by libc++, both now and in the future. In particular, inline 370 namespaces of the form ``__[0-9]+`` are strictly reserved by libc++ and may not be used by users. 371 Doing otherwise could cause conflicts and hinder libc++ ABI evolution. 372 373.. option:: LIBCXX_ABI_DEFINES:STRING 374 375 **Default**: ``""`` 376 377 A semicolon-separated list of ABI macros to persist in the site config header. 378 See ``include/__config`` for the list of ABI macros. 379 380 381.. option:: LIBCXX_TYPEINFO_COMPARISON_IMPLEMENTATION 382 383 **Default**: ``None``, which lets the library figure out which implementation 384 to use based on the object format. 385 386 This setting defines what implementation to use for comparing typeinfo objects. 387 There are two main implementations, which differ on whether we make the assumption 388 that type info names for a type have been fully merged are unique across the entire 389 program. This may not be the case for libraries built with ``-Bsymbolic`` or due to 390 compiler or linker bugs (Ex. llvm.org/PR37398). 391 392 393 When the value is set to ``1``, we assume that typeinfos are unique across the 394 whole program, and typeinfo comparisons compare only the pointer value. 395 396 When the value is set to ``2``, we do not assume that typeinfos are unique across 397 the whole program. We first compare the pointers, and then use ``strcmp`` on the 398 typeinfo names as a fallback. 399 400 401.. _LLVM-specific variables: 402 403LLVM-specific options 404--------------------- 405 406.. option:: LLVM_LIBDIR_SUFFIX:STRING 407 408 Extra suffix to append to the directory where libraries are to be 409 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 410 to install libraries to ``/usr/lib64``. 411 412.. option:: LLVM_BUILD_32_BITS:BOOL 413 414 Build 32-bits executables and libraries on 64-bits systems. This option is 415 available only on some 64-bits Unix systems. Defaults to OFF. 416 417.. option:: LLVM_LIT_ARGS:STRING 418 419 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 420 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 421 others. 422 423 424Using Alternate ABI libraries 425============================= 426 427 428.. _libsupcxx: 429 430Using libsupc++ on Linux 431------------------------ 432 433You will need libstdc++ in order to provide libsupc++. 434 435Figure out where the libsupc++ headers are on your system. On Ubuntu this 436is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 437 438You can also figure this out by running 439 440.. code-block:: bash 441 442 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 443 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 444 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 445 #include "..." search starts here: 446 #include <...> search starts here: 447 /usr/include/c++/4.7 448 /usr/include/c++/4.7/x86_64-linux-gnu 449 /usr/include/c++/4.7/backward 450 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 451 /usr/local/include 452 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 453 /usr/include/x86_64-linux-gnu 454 /usr/include 455 End of search list. 456 457Note that the first two entries happen to be what we are looking for. This 458may not be correct on other platforms. 459 460We can now run CMake: 461 462.. code-block:: bash 463 464 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 465 -DLIBCXX_CXX_ABI=libstdc++ \ 466 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 467 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 468 <libc++-source-dir> 469 470 471You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 472above, which will cause the library to be linked to libsupc++ instead 473of libstdc++, but this is only recommended if you know that you will 474never need to link against libstdc++ in the same executable as libc++. 475GCC ships libsupc++ separately but only as a static library. If a 476program also needs to link against libstdc++, it will provide its 477own copy of libsupc++ and this can lead to subtle problems. 478 479.. code-block:: bash 480 481 $ make cxx 482 $ make install 483 484You can now run clang with -stdlib=libc++. 485 486 487.. _libcxxrt_ref: 488 489Using libcxxrt on Linux 490------------------------ 491 492You will need to keep the source tree of `libcxxrt`_ available 493on your build machine and your copy of the libcxxrt shared library must 494be placed where your linker will find it. 495 496We can now run CMake like: 497 498.. code-block:: bash 499 500 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 501 -DLIBCXX_CXX_ABI=libcxxrt \ 502 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ 503 -DCMAKE_BUILD_TYPE=Release \ 504 -DCMAKE_INSTALL_PREFIX=/usr \ 505 <libc++-source-directory> 506 $ make cxx 507 $ make install 508 509Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 510clang is set up to link for libc++ linked to libsupc++. To get around this 511you'll have to set up your linker yourself (or patch clang). For example, 512 513.. code-block:: bash 514 515 $ clang++ -stdlib=libc++ helloworld.cpp \ 516 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 517 518Alternately, you could just add libcxxrt to your libraries list, which in most 519situations will give the same result: 520 521.. code-block:: bash 522 523 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 524 525.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ 526 527 528Using a local ABI library installation 529--------------------------------------- 530 531.. warning:: 532 This is not recommended in almost all cases. 533 534These instructions should only be used when you can't install your ABI library. 535 536Normally you must link libc++ against a ABI shared library that the 537linker can find. If you want to build and test libc++ against an ABI 538library not in the linker's path you need to set 539``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. 540 541An example build using libc++abi would look like: 542 543.. code-block:: bash 544 545 $ CC=clang CXX=clang++ cmake \ 546 -DLIBCXX_CXX_ABI=libc++abi \ 547 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ 548 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ 549 path/to/libcxx 550 $ make 551 552When testing libc++ LIT will automatically link against the proper ABI 553library. 554