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 95.. _`libc++abi`: http://libcxxabi.llvm.org/ 96 97 98.. _CMake Options: 99 100CMake Options 101============= 102 103Here are some of the CMake variables that are used often, along with a 104brief explanation and LLVM-specific notes. For full documentation, check the 105CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 106 107**CMAKE_BUILD_TYPE**:STRING 108 Sets the build type for ``make`` based generators. Possible values are 109 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 110 the user sets the build type with the IDE settings. 111 112**CMAKE_INSTALL_PREFIX**:PATH 113 Path where LLVM will be installed if "make install" is invoked or the 114 "INSTALL" target is built. 115 116**CMAKE_CXX_COMPILER**:STRING 117 The C++ compiler to use when building and testing libc++. 118 119 120.. _libcxx-specific options: 121 122libc++ specific options 123----------------------- 124 125.. option:: LIBCXX_INSTALL_LIBRARY:BOOL 126 127 **Default**: ``ON`` 128 129 Toggle the installation of the library portion of libc++. 130 131.. option:: LIBCXX_INSTALL_HEADERS:BOOL 132 133 **Default**: ``ON`` 134 135 Toggle the installation of the libc++ headers. 136 137.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL 138 139 **Default**: ``ON`` 140 141 Build libc++ with assertions enabled. 142 143.. option:: LIBCXX_BUILD_32_BITS:BOOL 144 145 **Default**: ``OFF`` 146 147 Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`. 148 149.. option:: LIBCXX_ENABLE_SHARED:BOOL 150 151 **Default**: ``ON`` 152 153 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or 154 `LIBCXX_ENABLE_STATIC` has to be enabled. 155 156.. option:: LIBCXX_ENABLE_STATIC:BOOL 157 158 **Default**: ``ON`` 159 160 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or 161 `LIBCXX_ENABLE_STATIC` has to be enabled. 162 163.. option:: LIBCXX_LIBDIR_SUFFIX:STRING 164 165 Extra suffix to append to the directory where libraries are to be installed. 166 This option overrides `LLVM_LIBDIR_SUFFIX`. 167 168 169.. _libc++experimental options: 170 171libc++experimental Specific Options 172------------------------------------ 173 174.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL 175 176 **Default**: ``ON`` 177 178 Build and test libc++experimental.a. 179 180.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL 181 182 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` 183 184 Install libc++experimental.a alongside libc++. 185 186 187.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL 188 189 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY`` 190 191 Build filesystem as part of libc++experimental.a. This allows filesystem 192 to be disabled without turning off the entire experimental library. 193 194 195.. _ABI Library Specific Options: 196 197ABI Library Specific Options 198---------------------------- 199 200.. option:: LIBCXX_CXX_ABI:STRING 201 202 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. 203 204 Select the ABI library to build libc++ against. 205 206.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS 207 208 Provide additional search paths for the ABI library headers. 209 210.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH 211 212 Provide the path to the ABI library that libc++ should link against. 213 214.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL 215 216 **Default**: ``OFF`` 217 218 If this option is enabled, libc++ will try and link the selected ABI library 219 statically. 220 221.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL 222 223 **Default**: ``ON`` by default on UNIX platforms other than Apple unless 224 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. 225 226 This option generate and installs a linker script as ``libc++.so`` which 227 links the correct ABI library. 228 229.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL 230 231 **Default**: ``OFF`` 232 233 Build and use the LLVM unwinder. Note: This option can only be used when 234 libc++abi is the C++ ABI library used. 235 236 237libc++ Feature Options 238---------------------- 239 240.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL 241 242 **Default**: ``ON`` 243 244 Build libc++ with exception support. 245 246.. option:: LIBCXX_ENABLE_RTTI:BOOL 247 248 **Default**: ``ON`` 249 250 Build libc++ with run time type information. 251 252.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 253 254 **Default**: ``ON`` 255 256 Build the libc++ benchmark tests and the Google Benchmark library needed 257 to support them. 258 259.. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING 260 261 **Default**:: ``""`` 262 263 **Values**:: ``libc++``, ``libstdc++`` 264 265 Build the libc++ benchmark tests and Google Benchmark library against the 266 specified standard library on the platform. On linux this can be used to 267 compare libc++ to libstdc++ by building the benchmark tests against both 268 standard libraries. 269 270.. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING 271 272 Use the specified GCC toolchain and standard library when building the native 273 stdlib benchmark tests. 274 275 276libc++ ABI Feature Options 277-------------------------- 278 279The following options allow building libc++ for a different ABI version. 280 281.. option:: LIBCXX_ABI_VERSION:STRING 282 283 **Default**: ``1`` 284 285 Defines the target ABI version of libc++. 286 287.. option:: LIBCXX_ABI_UNSTABLE:BOOL 288 289 **Default**: ``OFF`` 290 291 Build the "unstable" ABI version of libc++. Includes all ABI changing features 292 on top of the current stable version. 293 294.. _LLVM-specific variables: 295 296LLVM-specific options 297--------------------- 298 299.. option:: LLVM_LIBDIR_SUFFIX:STRING 300 301 Extra suffix to append to the directory where libraries are to be 302 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 303 to install libraries to ``/usr/lib64``. 304 305.. option:: LLVM_BUILD_32_BITS:BOOL 306 307 Build 32-bits executables and libraries on 64-bits systems. This option is 308 available only on some 64-bits unix systems. Defaults to OFF. 309 310.. option:: LLVM_LIT_ARGS:STRING 311 312 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 313 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 314 others. 315 316 317Using Alternate ABI libraries 318============================= 319 320 321.. _libsupcxx: 322 323Using libsupc++ on Linux 324------------------------ 325 326You will need libstdc++ in order to provide libsupc++. 327 328Figure out where the libsupc++ headers are on your system. On Ubuntu this 329is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` 330 331You can also figure this out by running 332 333.. code-block:: bash 334 335 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only 336 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" 337 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" 338 #include "..." search starts here: 339 #include <...> search starts here: 340 /usr/include/c++/4.7 341 /usr/include/c++/4.7/x86_64-linux-gnu 342 /usr/include/c++/4.7/backward 343 /usr/lib/gcc/x86_64-linux-gnu/4.7/include 344 /usr/local/include 345 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed 346 /usr/include/x86_64-linux-gnu 347 /usr/include 348 End of search list. 349 350Note that the first two entries happen to be what we are looking for. This 351may not be correct on other platforms. 352 353We can now run CMake: 354 355.. code-block:: bash 356 357 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 358 -DLIBCXX_CXX_ABI=libstdc++ \ 359 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ 360 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ 361 <libc++-source-dir> 362 363 364You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` 365above, which will cause the library to be linked to libsupc++ instead 366of libstdc++, but this is only recommended if you know that you will 367never need to link against libstdc++ in the same executable as libc++. 368GCC ships libsupc++ separately but only as a static library. If a 369program also needs to link against libstdc++, it will provide its 370own copy of libsupc++ and this can lead to subtle problems. 371 372.. code-block:: bash 373 374 $ make cxx 375 $ make install 376 377You can now run clang with -stdlib=libc++. 378 379 380.. _libcxxrt_ref: 381 382Using libcxxrt on Linux 383------------------------ 384 385You will need to keep the source tree of `libcxxrt`_ available 386on your build machine and your copy of the libcxxrt shared library must 387be placed where your linker will find it. 388 389We can now run CMake like: 390 391.. code-block:: bash 392 393 $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ 394 -DLIBCXX_CXX_ABI=libcxxrt \ 395 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ 396 -DCMAKE_BUILD_TYPE=Release \ 397 -DCMAKE_INSTALL_PREFIX=/usr \ 398 <libc++-source-directory> 399 $ make cxx 400 $ make install 401 402Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as 403clang is set up to link for libc++ linked to libsupc++. To get around this 404you'll have to set up your linker yourself (or patch clang). For example, 405 406.. code-block:: bash 407 408 $ clang++ -stdlib=libc++ helloworld.cpp \ 409 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc 410 411Alternately, you could just add libcxxrt to your libraries list, which in most 412situations will give the same result: 413 414.. code-block:: bash 415 416 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt 417 418.. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ 419 420 421Using a local ABI library installation 422--------------------------------------- 423 424.. warning:: 425 This is not recommended in almost all cases. 426 427These instructions should only be used when you can't install your ABI library. 428 429Normally you must link libc++ against a ABI shared library that the 430linker can find. If you want to build and test libc++ against an ABI 431library not in the linker's path you needq to set 432``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. 433 434An example build using libc++abi would look like: 435 436.. code-block:: bash 437 438 $ CC=clang CXX=clang++ cmake \ 439 -DLIBCXX_CXX_ABI=libc++abi \ 440 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ 441 -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ 442 path/to/libcxx 443 $ make 444 445When testing libc++ LIT will automatically link against the proper ABI 446library. 447