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