Eric Fiselier | d256280 | 2016-06-02 02:16:28 +0000 | [diff] [blame] | 1 | .. _BuildingLibcxx: |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 2 | |
| 3 | =============== |
| 4 | Building libc++ |
| 5 | =============== |
| 6 | |
| 7 | .. contents:: |
| 8 | :local: |
| 9 | |
Eric Fiselier | 7039fa1 | 2016-05-03 22:32:08 +0000 | [diff] [blame] | 10 | .. _build instructions: |
| 11 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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`` |
Eric Fiselier | 8459d20 | 2015-12-14 22:26:28 +0000 | [diff] [blame] | 29 | * ``cd llvm/projects`` |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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`` |
Eric Fiselier | 8459d20 | 2015-12-14 22:26:28 +0000 | [diff] [blame] | 36 | * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi`` |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 37 | |
| 38 | #. Configure and build libc++ with libc++abi: |
| 39 | |
Alexey Samsonov | d118e32 | 2016-01-30 01:11:42 +0000 | [diff] [blame] | 40 | CMake is the only supported configuration system. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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. |
Eric Fiselier | d3169f5 | 2016-08-28 18:33:08 +0000 | [diff] [blame] | 52 | * ``make check-cxx check-cxxabi`` --- will run the test suites. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | d3169f5 | 2016-08-28 18:33:08 +0000 | [diff] [blame] | 63 | * ``make install-cxx install-cxxabi`` --- Will install the libraries and the headers |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | b22481a | 2015-09-06 23:31:16 +0000 | [diff] [blame] | 74 | It is sometimes beneficial to build outside of the LLVM tree. An out-of-tree |
| 75 | build would look like this: |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Saleem Abdulrasool | e7bee0d | 2017-02-10 03:58:20 +0000 | [diff] [blame] | 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" ^ |
Hamza Sood | 9627e9b | 2017-12-03 10:18:35 +0000 | [diff] [blame] | 133 | -DCMAKE_CXX_COMPILER=clang-cl ^ |
Saleem Abdulrasool | e7bee0d | 2017-02-10 03:58:20 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | 7039fa1 | 2016-05-03 22:32:08 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | f05ac13 | 2016-09-16 03:47:53 +0000 | [diff] [blame] | 198 | Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 199 | |
| 200 | .. option:: LIBCXX_ENABLE_SHARED:BOOL |
| 201 | |
| 202 | **Default**: ``ON`` |
| 203 | |
Eric Fiselier | f05ac13 | 2016-09-16 03:47:53 +0000 | [diff] [blame] | 204 | Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or |
| 205 | `LIBCXX_ENABLE_STATIC` has to be enabled. |
Petr Hosek | b640da0 | 2016-08-08 22:57:25 +0000 | [diff] [blame] | 206 | |
| 207 | .. option:: LIBCXX_ENABLE_STATIC:BOOL |
| 208 | |
| 209 | **Default**: ``ON`` |
| 210 | |
Eric Fiselier | f05ac13 | 2016-09-16 03:47:53 +0000 | [diff] [blame] | 211 | Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or |
| 212 | `LIBCXX_ENABLE_STATIC` has to be enabled. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 213 | |
| 214 | .. option:: LIBCXX_LIBDIR_SUFFIX:STRING |
| 215 | |
| 216 | Extra suffix to append to the directory where libraries are to be installed. |
Eric Fiselier | f05ac13 | 2016-09-16 03:47:53 +0000 | [diff] [blame] | 217 | This option overrides `LLVM_LIBDIR_SUFFIX`. |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 218 | |
Petr Hosek | 347be61 | 2017-07-11 02:39:50 +0000 | [diff] [blame] | 219 | .. option:: LIBCXX_INSTALL_PREFIX:STRING |
| 220 | |
| 221 | **Default**: ``""`` |
| 222 | |
| 223 | Define libc++ destination prefix. |
Eric Fiselier | 7039fa1 | 2016-05-03 22:32:08 +0000 | [diff] [blame] | 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 | |
Eric Fiselier | 01609af | 2016-09-07 01:15:10 +0000 | [diff] [blame] | 238 | **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY`` |
Eric Fiselier | 7039fa1 | 2016-05-03 22:32:08 +0000 | [diff] [blame] | 239 | |
| 240 | Install libc++experimental.a alongside libc++. |
| 241 | |
| 242 | |
Eric Fiselier | 6e9a694 | 2016-06-17 19:46:40 +0000 | [diff] [blame] | 243 | .. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL |
| 244 | |
Eric Fiselier | a0866c5 | 2018-07-27 03:07:09 +0000 | [diff] [blame] | 245 | **Default**: ``ON`` |
Eric Fiselier | 6e9a694 | 2016-06-17 19:46:40 +0000 | [diff] [blame] | 246 | |
Eric Fiselier | a0866c5 | 2018-07-27 03:07:09 +0000 | [diff] [blame] | 247 | Build filesystem as a standalone library libc++fs.a. |
Eric Fiselier | 6e9a694 | 2016-06-17 19:46:40 +0000 | [diff] [blame] | 248 | |
Eric Fiselier | a0866c5 | 2018-07-27 03:07:09 +0000 | [diff] [blame] | 249 | .. option:: LIBCXX_INSTALL_FILESYSTEM_LIBRARY:BOOL |
| 250 | |
| 251 | **Default**: ``LIBCXX_ENABLE_FILESYSTEM AND LIBCXX_INSTALL_LIBRARY`` |
| 252 | |
| 253 | Install libc++fs.a alongside libc++. |
Eric Fiselier | 6e9a694 | 2016-06-17 19:46:40 +0000 | [diff] [blame] | 254 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 255 | .. _ABI Library Specific Options: |
| 256 | |
| 257 | ABI Library Specific Options |
| 258 | ---------------------------- |
| 259 | |
| 260 | .. option:: LIBCXX_CXX_ABI:STRING |
| 261 | |
| 262 | **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``. |
| 263 | |
| 264 | Select the ABI library to build libc++ against. |
| 265 | |
| 266 | .. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS |
| 267 | |
| 268 | Provide additional search paths for the ABI library headers. |
| 269 | |
| 270 | .. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH |
| 271 | |
| 272 | Provide the path to the ABI library that libc++ should link against. |
| 273 | |
| 274 | .. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL |
| 275 | |
| 276 | **Default**: ``OFF`` |
| 277 | |
| 278 | If this option is enabled, libc++ will try and link the selected ABI library |
| 279 | statically. |
| 280 | |
Eric Fiselier | bb856cc | 2015-10-15 22:41:51 +0000 | [diff] [blame] | 281 | .. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL |
| 282 | |
| 283 | **Default**: ``ON`` by default on UNIX platforms other than Apple unless |
| 284 | 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``. |
| 285 | |
| 286 | This option generate and installs a linker script as ``libc++.so`` which |
| 287 | links the correct ABI library. |
| 288 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 289 | .. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL |
| 290 | |
| 291 | **Default**: ``OFF`` |
| 292 | |
| 293 | Build and use the LLVM unwinder. Note: This option can only be used when |
| 294 | libc++abi is the C++ ABI library used. |
| 295 | |
| 296 | |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 297 | libc++ Feature Options |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 298 | ---------------------- |
| 299 | |
| 300 | .. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL |
| 301 | |
| 302 | **Default**: ``ON`` |
| 303 | |
| 304 | Build libc++ with exception support. |
| 305 | |
| 306 | .. option:: LIBCXX_ENABLE_RTTI:BOOL |
| 307 | |
| 308 | **Default**: ``ON`` |
| 309 | |
| 310 | Build libc++ with run time type information. |
| 311 | |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 312 | .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL |
Evgeniy Stepanov | 4f01aa8 | 2015-10-13 23:48:28 +0000 | [diff] [blame] | 313 | |
Eric Fiselier | 0a799bd | 2016-08-29 19:50:49 +0000 | [diff] [blame] | 314 | **Default**: ``ON`` |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 315 | |
| 316 | Build the libc++ benchmark tests and the Google Benchmark library needed |
| 317 | to support them. |
| 318 | |
Eric Fiselier | 2d2f0c0 | 2016-10-30 22:53:00 +0000 | [diff] [blame] | 319 | .. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 320 | |
Eric Fiselier | 2d2f0c0 | 2016-10-30 22:53:00 +0000 | [diff] [blame] | 321 | **Default**:: ``""`` |
| 322 | |
| 323 | **Values**:: ``libc++``, ``libstdc++`` |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 324 | |
| 325 | Build the libc++ benchmark tests and Google Benchmark library against the |
Eric Fiselier | 2d2f0c0 | 2016-10-30 22:53:00 +0000 | [diff] [blame] | 326 | specified standard library on the platform. On linux this can be used to |
| 327 | compare libc++ to libstdc++ by building the benchmark tests against both |
| 328 | standard libraries. |
| 329 | |
| 330 | .. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING |
| 331 | |
| 332 | Use the specified GCC toolchain and standard library when building the native |
| 333 | stdlib benchmark tests. |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 334 | |
Louis Dionne | 61b0a00 | 2018-08-16 12:44:28 +0000 | [diff] [blame] | 335 | .. option:: LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL |
| 336 | |
| 337 | **Default**: ``OFF`` |
| 338 | |
| 339 | Pick the default for whether to constrain ABI-unstable symbols to |
| 340 | each individual translation unit. This setting controls whether |
| 341 | `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined by default -- |
| 342 | see the documentation of that macro for details. |
| 343 | |
Eric Fiselier | d9b9ef7 | 2016-07-19 23:07:03 +0000 | [diff] [blame] | 344 | |
| 345 | libc++ ABI Feature Options |
| 346 | -------------------------- |
Evgeniy Stepanov | 4f01aa8 | 2015-10-13 23:48:28 +0000 | [diff] [blame] | 347 | |
| 348 | The following options allow building libc++ for a different ABI version. |
| 349 | |
| 350 | .. option:: LIBCXX_ABI_VERSION:STRING |
| 351 | |
| 352 | **Default**: ``1`` |
| 353 | |
| 354 | Defines the target ABI version of libc++. |
| 355 | |
| 356 | .. option:: LIBCXX_ABI_UNSTABLE:BOOL |
| 357 | |
| 358 | **Default**: ``OFF`` |
| 359 | |
| 360 | Build the "unstable" ABI version of libc++. Includes all ABI changing features |
| 361 | on top of the current stable version. |
| 362 | |
Shoaib Meenai | 2bba98e | 2017-10-04 23:17:12 +0000 | [diff] [blame] | 363 | .. option:: LIBCXX_ABI_DEFINES:STRING |
| 364 | |
| 365 | **Default**: ``""`` |
| 366 | |
| 367 | A semicolon-separated list of ABI macros to persist in the site config header. |
| 368 | See ``include/__config`` for the list of ABI macros. |
| 369 | |
Eric Fiselier | b9f425a | 2015-08-22 19:40:49 +0000 | [diff] [blame] | 370 | .. _LLVM-specific variables: |
| 371 | |
| 372 | LLVM-specific options |
| 373 | --------------------- |
| 374 | |
| 375 | .. option:: LLVM_LIBDIR_SUFFIX:STRING |
| 376 | |
| 377 | Extra suffix to append to the directory where libraries are to be |
| 378 | installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` |
| 379 | to install libraries to ``/usr/lib64``. |
| 380 | |
| 381 | .. option:: LLVM_BUILD_32_BITS:BOOL |
| 382 | |
| 383 | Build 32-bits executables and libraries on 64-bits systems. This option is |
| 384 | available only on some 64-bits unix systems. Defaults to OFF. |
| 385 | |
| 386 | .. option:: LLVM_LIT_ARGS:STRING |
| 387 | |
| 388 | Arguments given to lit. ``make check`` and ``make clang-test`` are affected. |
| 389 | By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on |
| 390 | others. |
| 391 | |
| 392 | |
| 393 | Using Alternate ABI libraries |
| 394 | ============================= |
| 395 | |
| 396 | |
| 397 | .. _libsupcxx: |
| 398 | |
| 399 | Using libsupc++ on Linux |
| 400 | ------------------------ |
| 401 | |
| 402 | You will need libstdc++ in order to provide libsupc++. |
| 403 | |
| 404 | Figure out where the libsupc++ headers are on your system. On Ubuntu this |
| 405 | is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>`` |
| 406 | |
| 407 | You can also figure this out by running |
| 408 | |
| 409 | .. code-block:: bash |
| 410 | |
| 411 | $ echo | g++ -Wp,-v -x c++ - -fsyntax-only |
| 412 | ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu" |
| 413 | ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include" |
| 414 | #include "..." search starts here: |
| 415 | #include <...> search starts here: |
| 416 | /usr/include/c++/4.7 |
| 417 | /usr/include/c++/4.7/x86_64-linux-gnu |
| 418 | /usr/include/c++/4.7/backward |
| 419 | /usr/lib/gcc/x86_64-linux-gnu/4.7/include |
| 420 | /usr/local/include |
| 421 | /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed |
| 422 | /usr/include/x86_64-linux-gnu |
| 423 | /usr/include |
| 424 | End of search list. |
| 425 | |
| 426 | Note that the first two entries happen to be what we are looking for. This |
| 427 | may not be correct on other platforms. |
| 428 | |
| 429 | We can now run CMake: |
| 430 | |
| 431 | .. code-block:: bash |
| 432 | |
| 433 | $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ |
| 434 | -DLIBCXX_CXX_ABI=libstdc++ \ |
| 435 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/" \ |
| 436 | -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \ |
| 437 | <libc++-source-dir> |
| 438 | |
| 439 | |
| 440 | You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++`` |
| 441 | above, which will cause the library to be linked to libsupc++ instead |
| 442 | of libstdc++, but this is only recommended if you know that you will |
| 443 | never need to link against libstdc++ in the same executable as libc++. |
| 444 | GCC ships libsupc++ separately but only as a static library. If a |
| 445 | program also needs to link against libstdc++, it will provide its |
| 446 | own copy of libsupc++ and this can lead to subtle problems. |
| 447 | |
| 448 | .. code-block:: bash |
| 449 | |
| 450 | $ make cxx |
| 451 | $ make install |
| 452 | |
| 453 | You can now run clang with -stdlib=libc++. |
Eric Fiselier | d256280 | 2016-06-02 02:16:28 +0000 | [diff] [blame] | 454 | |
| 455 | |
| 456 | .. _libcxxrt_ref: |
| 457 | |
| 458 | Using libcxxrt on Linux |
| 459 | ------------------------ |
| 460 | |
| 461 | You will need to keep the source tree of `libcxxrt`_ available |
| 462 | on your build machine and your copy of the libcxxrt shared library must |
| 463 | be placed where your linker will find it. |
| 464 | |
| 465 | We can now run CMake like: |
| 466 | |
| 467 | .. code-block:: bash |
| 468 | |
| 469 | $ CC=clang CXX=clang++ cmake -G "Unix Makefiles" \ |
| 470 | -DLIBCXX_CXX_ABI=libcxxrt \ |
| 471 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src \ |
| 472 | -DCMAKE_BUILD_TYPE=Release \ |
| 473 | -DCMAKE_INSTALL_PREFIX=/usr \ |
| 474 | <libc++-source-directory> |
| 475 | $ make cxx |
| 476 | $ make install |
| 477 | |
| 478 | Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as |
| 479 | clang is set up to link for libc++ linked to libsupc++. To get around this |
| 480 | you'll have to set up your linker yourself (or patch clang). For example, |
| 481 | |
| 482 | .. code-block:: bash |
| 483 | |
| 484 | $ clang++ -stdlib=libc++ helloworld.cpp \ |
| 485 | -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc |
| 486 | |
| 487 | Alternately, you could just add libcxxrt to your libraries list, which in most |
| 488 | situations will give the same result: |
| 489 | |
| 490 | .. code-block:: bash |
| 491 | |
| 492 | $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt |
| 493 | |
| 494 | .. _`libcxxrt`: https://github.com/pathscale/libcxxrt/ |
| 495 | |
| 496 | |
| 497 | Using a local ABI library installation |
| 498 | --------------------------------------- |
| 499 | |
| 500 | .. warning:: |
| 501 | This is not recommended in almost all cases. |
| 502 | |
| 503 | These instructions should only be used when you can't install your ABI library. |
| 504 | |
| 505 | Normally you must link libc++ against a ABI shared library that the |
| 506 | linker can find. If you want to build and test libc++ against an ABI |
| 507 | library not in the linker's path you needq to set |
| 508 | ``-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib`` when configuring CMake. |
| 509 | |
| 510 | An example build using libc++abi would look like: |
| 511 | |
| 512 | .. code-block:: bash |
| 513 | |
| 514 | $ CC=clang CXX=clang++ cmake \ |
| 515 | -DLIBCXX_CXX_ABI=libc++abi \ |
| 516 | -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/path/to/libcxxabi/include" \ |
| 517 | -DLIBCXX_CXX_ABI_LIBRARY_PATH="/path/to/libcxxabi-build/lib" \ |
| 518 | path/to/libcxx |
| 519 | $ make |
| 520 | |
| 521 | When testing libc++ LIT will automatically link against the proper ABI |
| 522 | library. |