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