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 220 .. _libc++experimental options: 221 222 libc++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 .. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 239 240 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY`` 241 242 Build filesystem as part of libc++experimental.a. This allows filesystem 243 to be disabled without turning off the entire experimental library. 244 245 246 .. _ABI Library Specific Options: 247 248 ABI Library Specific Options 249 ---------------------------- 250 251 .. option:: LIBCXX_CXX_ABI:STRING 252 253 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. 254 255 Select the ABI library to build libc++ against. 256 257 .. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 258 259 Provide additional search paths for the ABI library headers. 260 261 .. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 262 263 Provide the path to the ABI library that libc++ should link against. 264 265 .. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 266 267 **Default**: ``OFF`` 268 269 If this option is enabled, libc++ will try and link the selected ABI library 270 statically. 271 272 .. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 273 274 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 275 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 276 277 This option generate and installs a linker script as ``libc++.so`` which 278 links the correct ABI library. 279 280 .. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 281 282 **Default**: ``OFF`` 283 284 Build and use the LLVM unwinder. Note: This option can only be used when 285 libc++abi is the C++ ABI library used. 286 287 288 libc++ Feature Options 289 ---------------------- 290 291 .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 292 293 **Default**: ``ON`` 294 295 Build libc++ with exception support. 296 297 .. option:: LIBCXX_ENABLE_RTTI:BOOL 298 299 **Default**: ``ON`` 300 301 Build libc++ with run time type information. 302 303 .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 304 305 **Default**: ``ON`` 306 307 Build the libc++ benchmark tests and the Google Benchmark library needed 308 to support them. 309 310 .. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING 311 312 **Default**:: ``""`` 313 314 **Values**:: ``libc++``, ``libstdc++`` 315 316 Build the libc++ benchmark tests and Google Benchmark library against the 317 specified standard library on the platform. On linux this can be used to 318 compare libc++ to libstdc++ by building the benchmark tests against both 319 standard libraries. 320 321 .. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING 322 323 Use the specified GCC toolchain and standard library when building the native 324 stdlib benchmark tests. 325 326 327 libc++ ABI Feature Options 328 -------------------------- 329 330 The following options allow building libc++ for a different ABI version. 331 332 .. option:: LIBCXX_ABI_VERSION:STRING 333 334 **Default**: ``1`` 335 336 Defines the target ABI version of libc++. 337 338 .. option:: LIBCXX_ABI_UNSTABLE:BOOL 339 340 **Default**: ``OFF`` 341 342 Build the "unstable" ABI version of libc++. Includes all ABI changing features 343 on top of the current stable version. 344 345 .. _LLVM-specific variables: 346 347 LLVM-specific options 348 --------------------- 349 350 .. option:: LLVM_LIBDIR_SUFFIX:STRING 351 352 Extra suffix to append to the directory where libraries are to be 353 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 354 to install libraries to ``/usr/lib64``. 355 356 .. option:: LLVM_BUILD_32_BITS:BOOL 357 358 Build 32-bits executables and libraries on 64-bits systems. This option is 359 available only on some 64-bits unix systems. Defaults to OFF. 360 361 .. option:: LLVM_LIT_ARGS:STRING 362 363 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 364 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 365 others. 366 367 368 Using Alternate ABI libraries 369 ============================= 370 371 372 .. _libsupcxx: 373 374 Using libsupc++ on Linux 375 ------------------------ 376 377 You will need libstdc++ in order to provide libsupc++. 378 379 Figure out where the libsupc++ headers are on your system. On Ubuntu this 380 is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 381 382 You can also figure this out by running 383 384 .. code-block:: bash 385 386 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 387 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 388 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 389 #include "..." search starts here: 390 #include <...> search starts here: 391 /usr/include/c++/4.7 392 /usr/include/c++/4.7/x86_64-linux-gnu 393 /usr/include/c++/4.7/backward 394 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 395 /usr/local/include 396 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 397 /usr/include/x86_64-linux-gnu 398 /usr/include 399 End of search list. 400 401 Note that the first two entries happen to be what we are looking for. This 402 may not be correct on other platforms. 403 404 We can now run CMake: 405 406 .. code-block:: bash 407 408 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 409 -DLIBCXX_CXX_ABI=libstdc++ \ 410 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 411 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 412 <libc++-source-dir> 413 414 415 You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 416 above, which will cause the library to be linked to libsupc++ instead 417 of libstdc++, but this is only recommended if you know that you will 418 never need to link against libstdc++ in the same executable as libc++. 419 GCC ships libsupc++ separately but only as a static library. If a 420 program also needs to link against libstdc++, it will provide its 421 own copy of libsupc++ and this can lead to subtle problems. 422 423 .. code-block:: bash 424 425 $ make cxx 426 $ make install 427 428 You can now run clang with -stdlib=libc++. 429 430 431 .. _libcxxrt_ref: 432 433 Using libcxxrt on Linux 434 ------------------------ 435 436 You will need to keep the source tree of `libcxxrt`_ available 437 on your build machine and your copy of the libcxxrt shared library must 438 be placed where your linker will find it. 439 440 We can now run CMake like: 441 442 .. code-block:: bash 443 444 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 445 -DLIBCXX_CXX_ABI=libcxxrt \ 446 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ 447 -DCMAKE_BUILD_TYPE=Release \ 448 -DCMAKE_INSTALL_PREFIX=/usr \ 449 <libc++-source-directory> 450 $ make cxx 451 $ make install 452 453 Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 454 clang is set up to link for libc++ linked to libsupc++. To get around this 455 you'll have to set up your linker yourself (or patch clang). For example, 456 457 .. code-block:: bash 458 459 $ clang++ -stdlib=libc++ helloworld.cpp \ 460 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 461 462 Alternately, you could just add libcxxrt to your libraries list, which in most 463 situations will give the same result: 464 465 .. code-block:: bash 466 467 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 468 469 .. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ 470 471 472 Using a local ABI library installation 473 --------------------------------------- 474 475 .. warning:: 476 This is not recommended in almost all cases. 477 478 These instructions should only be used when you can't install your ABI library. 479 480 Normally you must link libc++ against a ABI shared library that the 481 linker can find. If you want to build and test libc++ against an ABI 482 library not in the linker's path you needq to set 483 ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. 484 485 An example build using libc++abi would look like: 486 487 .. code-block:: bash 488 489 $ CC=clang CXX=clang++ cmake \ 490 -DLIBCXX_CXX_ABI=libc++abi \ 491 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ 492 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ 493 path/to/libcxx 494 $ make 495 496 When testing libc++ LIT will automatically link against the proper ABI 497 library. 498
