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.. _LLVM-specific variables: 382 383LLVM-specific options 384--------------------- 385 386.. option:: LLVM_LIBDIR_SUFFIX:STRING 387 388 Extra suffix to append to the directory where libraries are to be 389 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 390 to install libraries to ``/usr/lib64``. 391 392.. option:: LLVM_BUILD_32_BITS:BOOL 393 394 Build 32-bits executables and libraries on 64-bits systems. This option is 395 available only on some 64-bits Unix systems. Defaults to OFF. 396 397.. option:: LLVM_LIT_ARGS:STRING 398 399 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 400 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 401 others. 402 403 404Using Alternate ABI libraries 405============================= 406 407 408.. _libsupcxx: 409 410Using libsupc++ on Linux 411------------------------ 412 413You will need libstdc++ in order to provide libsupc++. 414 415Figure out where the libsupc++ headers are on your system. On Ubuntu this 416is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 417 418You can also figure this out by running 419 420.. code-block:: bash 421 422 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 423 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 424 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 425 #include "..." search starts here: 426 #include <...> search starts here: 427 /usr/include/c++/4.7 428 /usr/include/c++/4.7/x86_64-linux-gnu 429 /usr/include/c++/4.7/backward 430 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 431 /usr/local/include 432 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 433 /usr/include/x86_64-linux-gnu 434 /usr/include 435 End of search list. 436 437Note that the first two entries happen to be what we are looking for. This 438may not be correct on other platforms. 439 440We can now run CMake: 441 442.. code-block:: bash 443 444 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 445 -DLIBCXX_CXX_ABI=libstdc++ \ 446 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 447 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 448 <libc++-source-dir> 449 450 451You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 452above, which will cause the library to be linked to libsupc++ instead 453of libstdc++, but this is only recommended if you know that you will 454never need to link against libstdc++ in the same executable as libc++. 455GCC ships libsupc++ separately but only as a static library. If a 456program also needs to link against libstdc++, it will provide its 457own copy of libsupc++ and this can lead to subtle problems. 458 459.. code-block:: bash 460 461 $ make cxx 462 $ make install 463 464You can now run clang with -stdlib=libc++. 465 466 467.. _libcxxrt_ref: 468 469Using libcxxrt on Linux 470------------------------ 471 472You will need to keep the source tree of `libcxxrt`_ available 473on your build machine and your copy of the libcxxrt shared library must 474be placed where your linker will find it. 475 476We can now run CMake like: 477 478.. code-block:: bash 479 480 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 481 -DLIBCXX_CXX_ABI=libcxxrt \ 482 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ 483 -DCMAKE_BUILD_TYPE=Release \ 484 -DCMAKE_INSTALL_PREFIX=/usr \ 485 <libc++-source-directory> 486 $ make cxx 487 $ make install 488 489Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 490clang is set up to link for libc++ linked to libsupc++. To get around this 491you'll have to set up your linker yourself (or patch clang). For example, 492 493.. code-block:: bash 494 495 $ clang++ -stdlib=libc++ helloworld.cpp \ 496 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 497 498Alternately, you could just add libcxxrt to your libraries list, which in most 499situations will give the same result: 500 501.. code-block:: bash 502 503 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 504 505.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ 506 507 508Using a local ABI library installation 509--------------------------------------- 510 511.. warning:: 512 This is not recommended in almost all cases. 513 514These instructions should only be used when you can't install your ABI library. 515 516Normally you must link libc++ against a ABI shared library that the 517linker can find. If you want to build and test libc++ against an ABI 518library not in the linker's path you need to set 519``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. 520 521An example build using libc++abi would look like: 522 523.. code-block:: bash 524 525 $ CC=clang CXX=clang++ cmake \ 526 -DLIBCXX_CXX_ABI=libc++abi \ 527 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ 528 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ 529 path/to/libcxx 530 $ make 531 532When testing libc++ LIT will automatically link against the proper ABI 533library. 534