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