1 .. _BuildingLibcxx: 2 3 =============== 4 Building libc++ 5 =============== 6 7 .. contents:: 8 :local: 9 10 .. _build instructions: 11 12 Getting Started 13 =============== 14 15 On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install 16 Xcode 4.2 or later. However if you want to install tip-of-trunk from here 17 (getting the bleeding edge), read on. 18 19 The 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 70 The instructions are for building libc++ on 71 FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library. 72 On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt. 73 74 It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree 75 build 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 95 Experimental Support for Windows 96 -------------------------------- 97 98 The Windows support requires building with clang-cl as cl does not support one 99 required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is 100 required. In the case of clang-cl, we need to specify the "MS Compatibility 101 Version" as it defaults to 2014 (18.00). 102 103 CMake + Visual Studio 104 ~~~~~~~~~~~~~~~~~~~~~ 105 106 Building with Visual Studio currently does not permit running tests. However, 107 it 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 119 CMake + ninja 120 ~~~~~~~~~~~~~ 121 122 Building with ninja is required for development to enable tests. 123 Unfortunately, doing so requires additional configuration as we cannot 124 just 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 143 Note that the paths specified with backward slashes must use the `\\` as the 144 directory 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 151 CMake Options 152 ============= 153 154 Here are some of the CMake variables that are used often, along with a 155 brief explanation and LLVM-specific notes. For full documentation, check the 156 CMake 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 173 libc++ 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 .. _libc++experimental options: 226 227 libc++experimental Specific Options 228 ------------------------------------ 229 230 .. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL 231 232 **Default**: ``ON`` 233 234 Build and test libc++experimental.a. 235 236 .. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL 237 238 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` 239 240 Install libc++experimental.a alongside libc++. 241 242 243 .. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 244 245 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY`` 246 247 Build filesystem as part of libc++experimental.a. This allows filesystem 248 to be disabled without turning off the entire experimental library. 249 250 251 .. _ABI Library Specific Options: 252 253 ABI Library Specific Options 254 ---------------------------- 255 256 .. option:: LIBCXX_CXX_ABI:STRING 257 258 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. 259 260 Select the ABI library to build libc++ against. 261 262 .. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 263 264 Provide additional search paths for the ABI library headers. 265 266 .. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 267 268 Provide the path to the ABI library that libc++ should link against. 269 270 .. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 271 272 **Default**: ``OFF`` 273 274 If this option is enabled, libc++ will try and link the selected ABI library 275 statically. 276 277 .. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 278 279 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 280 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 281 282 This option generate and installs a linker script as ``libc++.so`` which 283 links the correct ABI library. 284 285 .. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 286 287 **Default**: ``OFF`` 288 289 Build and use the LLVM unwinder. Note: This option can only be used when 290 libc++abi is the C++ ABI library used. 291 292 293 libc++ Feature Options 294 ---------------------- 295 296 .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 297 298 **Default**: ``ON`` 299 300 Build libc++ with exception support. 301 302 .. option:: LIBCXX_ENABLE_RTTI:BOOL 303 304 **Default**: ``ON`` 305 306 Build libc++ with run time type information. 307 308 .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 309 310 **Default**: ``ON`` 311 312 Build the libc++ benchmark tests and the Google Benchmark library needed 313 to support them. 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 332 libc++ ABI Feature Options 333 -------------------------- 334 335 The following options allow building libc++ for a different ABI version. 336 337 .. option:: LIBCXX_ABI_VERSION:STRING 338 339 **Default**: ``1`` 340 341 Defines the target ABI version of libc++. 342 343 .. option:: LIBCXX_ABI_UNSTABLE:BOOL 344 345 **Default**: ``OFF`` 346 347 Build the "unstable" ABI version of libc++. Includes all ABI changing features 348 on top of the current stable version. 349 350 .. option:: LIBCXX_ABI_DEFINES:STRING 351 352 **Default**: ``""`` 353 354 A semicolon-separated list of ABI macros to persist in the site config header. 355 See ``include/__config`` for the list of ABI macros. 356 357 .. _LLVM-specific variables: 358 359 LLVM-specific options 360 --------------------- 361 362 .. option:: LLVM_LIBDIR_SUFFIX:STRING 363 364 Extra suffix to append to the directory where libraries are to be 365 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 366 to install libraries to ``/usr/lib64``. 367 368 .. option:: LLVM_BUILD_32_BITS:BOOL 369 370 Build 32-bits executables and libraries on 64-bits systems. This option is 371 available only on some 64-bits unix systems. Defaults to OFF. 372 373 .. option:: LLVM_LIT_ARGS:STRING 374 375 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 376 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 377 others. 378 379 380 Using Alternate ABI libraries 381 ============================= 382 383 384 .. _libsupcxx: 385 386 Using libsupc++ on Linux 387 ------------------------ 388 389 You will need libstdc++ in order to provide libsupc++. 390 391 Figure out where the libsupc++ headers are on your system. On Ubuntu this 392 is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 393 394 You can also figure this out by running 395 396 .. code-block:: bash 397 398 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 399 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 400 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 401 #include "..." search starts here: 402 #include <...> search starts here: 403 /usr/include/c++/4.7 404 /usr/include/c++/4.7/x86_64-linux-gnu 405 /usr/include/c++/4.7/backward 406 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 407 /usr/local/include 408 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 409 /usr/include/x86_64-linux-gnu 410 /usr/include 411 End of search list. 412 413 Note that the first two entries happen to be what we are looking for. This 414 may not be correct on other platforms. 415 416 We can now run CMake: 417 418 .. code-block:: bash 419 420 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 421 -DLIBCXX_CXX_ABI=libstdc++ \ 422 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 423 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 424 <libc++-source-dir> 425 426 427 You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 428 above, which will cause the library to be linked to libsupc++ instead 429 of libstdc++, but this is only recommended if you know that you will 430 never need to link against libstdc++ in the same executable as libc++. 431 GCC ships libsupc++ separately but only as a static library. If a 432 program also needs to link against libstdc++, it will provide its 433 own copy of libsupc++ and this can lead to subtle problems. 434 435 .. code-block:: bash 436 437 $ make cxx 438 $ make install 439 440 You can now run clang with -stdlib=libc++. 441 442 443 .. _libcxxrt_ref: 444 445 Using libcxxrt on Linux 446 ------------------------ 447 448 You will need to keep the source tree of `libcxxrt`_ available 449 on your build machine and your copy of the libcxxrt shared library must 450 be placed where your linker will find it. 451 452 We can now run CMake like: 453 454 .. code-block:: bash 455 456 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 457 -DLIBCXX_CXX_ABI=libcxxrt \ 458 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ 459 -DCMAKE_BUILD_TYPE=Release \ 460 -DCMAKE_INSTALL_PREFIX=/usr \ 461 <libc++-source-directory> 462 $ make cxx 463 $ make install 464 465 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 466 clang is set up to link for libc++ linked to libsupc++. To get around this 467 you'll have to set up your linker yourself (or patch clang). For example, 468 469 .. code-block:: bash 470 471 $ clang++ -stdlib=libc++ helloworld.cpp \ 472 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 473 474 Alternately, you could just add libcxxrt to your libraries list, which in most 475 situations will give the same result: 476 477 .. code-block:: bash 478 479 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 480 481 .. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ 482 483 484 Using a local ABI library installation 485 --------------------------------------- 486 487 .. warning:: 488 This is not recommended in almost all cases. 489 490 These instructions should only be used when you can't install your ABI library. 491 492 Normally you must link libc++ against a ABI shared library that the 493 linker can find. If you want to build and test libc++ against an ABI 494 library not in the linker's path you needq to set 495 ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. 496 497 An example build using libc++abi would look like: 498 499 .. code-block:: bash 500 501 $ CC=clang CXX=clang++ cmake \ 502 -DLIBCXX_CXX_ABI=libc++abi \ 503 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ 504 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ 505 path/to/libcxx 506 $ make 507 508 When testing libc++ LIT will automatically link against the proper ABI 509 library. 510
