blob: 629e4c8355ba5b54dad95188e564bc225d03e4d3 [file] [log] [blame]
Eric Fiseliera0733922016-06-02 02:16:28 +00001.. _BuildingLibcxx:
Eric Fiselierd720d1f2015-08-22 19:40:49 +00002
3===============
4Building libc++
5===============
6
7.. contents::
8 :local:
9
Eric Fiselierfa43a5c2016-05-03 22:32:08 +000010.. _build instructions:
11
Louis Dionne4b1b70d2021-07-06 10:39:01 -040012The instructions on this page are aimed at vendors who ship libc++ as part of an
13operating system distribution, a toolchain or similar shipping vehicules. If you
14are a user merely trying to use libc++ in your program, you most likely want to
15refer to your vendor's documentation, or to the general documentation for using
16libc++ :ref:`here <using-libcxx>`.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000017
Dan Albert08302aa2019-11-07 12:40:05 -080018.. warning::
Louis Dionne4b1b70d2021-07-06 10:39:01 -040019 If your operating system already provides libc++, it is important to be careful
20 not to replace it. Replacing your system's libc++ installation could render it
21 non-functional. Use the CMake option ``CMAKE_INSTALL_PREFIX`` to select a safe
22 place to install libc++.
23
24
25The default build
26=================
27
28By default, libc++ and libc++abi are built as sub-projects of the LLVM project.
29This can be achieved with the usual CMake invocation:
Eric Fiselierd720d1f2015-08-22 19:40:49 +000030
Dan Albert08302aa2019-11-07 12:40:05 -080031.. code-block:: bash
Eric Fiselierd720d1f2015-08-22 19:40:49 +000032
Dan Albert08302aa2019-11-07 12:40:05 -080033 $ git clone https://github.com/llvm/llvm-project.git
34 $ cd llvm-project
Louis Dionne4b1b70d2021-07-06 10:39:01 -040035 $ mkdir build
36 $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="libcxx;libcxxabi" # Configure
37 $ ninja -C build cxx cxxabi # Build
38 $ ninja -C build check-cxx check-cxxabi # Test
39 $ ninja -C build install-cxx install-cxxabi # Install
Eric Fiselierd720d1f2015-08-22 19:40:49 +000040
Louis Dionne4b1b70d2021-07-06 10:39:01 -040041.. note::
42 See :ref:`CMake Options` below for more configuration options.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000043
Louis Dionne4b1b70d2021-07-06 10:39:01 -040044After building the ``install-cxx`` and ``install-cxxabi`` targets, shared libraries
45for libc++ and libc++abi should now be present in ``<CMAKE_INSTALL_PREFIX>/lib``, and
46headers in ``<CMAKE_INSTALL_PREFIX>/include/c++/v1``. See :ref:`using an alternate
47libc++ installation <alternate libcxx>` for information on how to use this libc++ over
48the default one.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000049
Louis Dionne4b1b70d2021-07-06 10:39:01 -040050In the default configuration, libc++ and libc++abi will be built using the compiler available
51by default on your system. It is also possible to bootstrap Clang and build libc++ with it.
Eric Fiselierd720d1f2015-08-22 19:40:49 +000052
Louis Dionne4b1b70d2021-07-06 10:39:01 -040053
54Bootstrapping build
55===================
56
57It is also possible to build Clang and then build libc++ and libc++abi using that
58just-built compiler. This is the correct way to build libc++ when putting together
59a toolchain, or when the system compiler is not adequate to build libc++ (too old,
60unsupported, etc.). This type of build is also commonly called a "Runtimes build":
Eric Fiselierd720d1f2015-08-22 19:40:49 +000061
62.. code-block:: bash
63
Louis Dionne4b1b70d2021-07-06 10:39:01 -040064 $ mkdir build
65 $ cmake -G Ninja -S llvm -B build -DLLVM_ENABLE_PROJECTS="clang" \ # Configure
66 -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi" \
67 -DLLVM_RUNTIME_TARGETS="<target-triple>"
68 $ ninja -C build runtimes # Build
69 $ ninja -C build check-runtimes # Test
70 $ ninja -C build install-runtimes # Install
Eric Fiselierd720d1f2015-08-22 19:40:49 +000071
72
Martin Storsjöf9535f72021-02-22 01:20:28 +020073Support for Windows
Louis Dionne4b1b70d2021-07-06 10:39:01 -040074===================
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +000075
Martin Storsjöf9535f72021-02-22 01:20:28 +020076libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as
Martin Storsjöbb9586b2021-03-17 11:40:17 +020077cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
Martin Storsjöf9535f72021-02-22 01:20:28 +020078newer (19.14) is required.
79
80libcxx also supports being built with clang targeting MinGW environments.
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +000081
82CMake + Visual Studio
Louis Dionne4b1b70d2021-07-06 10:39:01 -040083---------------------
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +000084
85Building with Visual Studio currently does not permit running tests. However,
86it is the simplest way to build.
87
88.. code-block:: batch
89
Louis Dionne4b1b70d2021-07-06 10:39:01 -040090 > cmake -G "Visual Studio 16 2019" -S libcxx -B build ^
91 -T "ClangCL" ^
92 -DLIBCXX_ENABLE_SHARED=YES ^
93 -DLIBCXX_ENABLE_STATIC=NO ^
94 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO
95 > cmake --build build
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +000096
Martin Storsjöf9535f72021-02-22 01:20:28 +020097CMake + ninja (MSVC)
Louis Dionne4b1b70d2021-07-06 10:39:01 -040098--------------------
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +000099
100Building with ninja is required for development to enable tests.
Martin Storsjö9728c102021-05-03 22:14:00 +0300101A couple of tests require Bash to be available, and a couple dozens
102of tests require other posix tools (cp, grep and similar - LLVM's tests
103require the same). Without those tools the vast majority of tests
104can still be ran successfully.
Martin Storsjöf9535f72021-02-22 01:20:28 +0200105
106If Git for Windows is available, that can be used to provide the bash
107shell by adding the right bin directory to the path, e.g.
Martin Storsjöbb9586b2021-03-17 11:40:17 +0200108``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
Martin Storsjöf9535f72021-02-22 01:20:28 +0200109
110Alternatively, one can also choose to run the whole build in a MSYS2
111shell. That can be set up e.g. by starting a Visual Studio Tools Command
112Prompt (for getting the environment variables pointing to the headers and
113import libraries), and making sure that clang-cl is available in the
114path. From there, launch an MSYS2 shell via e.g.
Martin Storsjöbb9586b2021-03-17 11:40:17 +0200115``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
Martin Storsjöf9535f72021-02-22 01:20:28 +0200116environment, allowing the MSVC headers/libraries and clang-cl to be found).
117
118In either case, then run:
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +0000119
120.. code-block:: batch
121
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400122 > cmake -G Ninja -S libcxx -B build ^
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +0000123 -DCMAKE_C_COMPILER=clang-cl ^
Martin Storsjöf9535f72021-02-22 01:20:28 +0200124 -DCMAKE_CXX_COMPILER=clang-cl ^
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400125 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO
126 > ninja -C build cxx
127 > ninja -C build check-cxx
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +0000128
Martin Storsjöf9535f72021-02-22 01:20:28 +0200129If you are running in an MSYS2 shell and you have installed the
130MSYS2-provided clang package (which defaults to a non-MSVC target), you
Martin Storsjöbb9586b2021-03-17 11:40:17 +0200131should add e.g. ``-DLIBCXX_TARGET_TRIPLE=x86_64-windows-msvc`` (replacing
132``x86_64`` with the architecture you're targeting) to the ``cmake`` command
133line above. This will instruct ``check-cxx`` to use the right target triple
134when invoking ``clang++``.
Martin Storsjöf9535f72021-02-22 01:20:28 +0200135
136Also note that if not building in Release mode, a failed assert in the tests
137pops up a blocking dialog box, making it hard to run a larger number of tests.
138
139CMake + ninja (MinGW)
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400140---------------------
Martin Storsjöf9535f72021-02-22 01:20:28 +0200141
142libcxx can also be built in MinGW environments, e.g. with the MinGW
143compilers in MSYS2. This requires clang to be available (installed with
Martin Storsjöbb9586b2021-03-17 11:40:17 +0200144e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
Martin Storsjöf9535f72021-02-22 01:20:28 +0200145
146.. code-block:: bash
147
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400148 > cmake -G Ninja -S libcxx -B build \
Martin Storsjöf9535f72021-02-22 01:20:28 +0200149 -DCMAKE_C_COMPILER=clang \
150 -DCMAKE_CXX_COMPILER=clang++ \
151 -DLIBCXX_HAS_WIN32_THREAD_API=ON \
152 -DLIBCXX_CXX_ABI=libstdc++ \
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400153 -DLIBCXX_TARGET_INFO="libcxx.test.target_info.MingwLocalTI"
154 > ninja -C build cxx
Martin Storsjöf9535f72021-02-22 01:20:28 +0200155 > cp /mingw64/bin/{libstdc++-6,libgcc_s_seh-1,libwinpthread-1}.dll lib
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400156 > ninja -C build check-cxx
Martin Storsjöf9535f72021-02-22 01:20:28 +0200157
158As this build configuration ends up depending on a couple other DLLs that
159aren't available in path while running tests, copy them into the same
160directory as the tested libc++ DLL.
161
162(Building a libc++ that depends on libstdc++ isn't necessarily a config one
163would want to deploy, but it simplifies the config for testing purposes.)
Saleem Abdulrasool3ab0b702017-02-10 03:58:20 +0000164
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000165.. _`libc++abi`: http://libcxxabi.llvm.org/
166
167
168.. _CMake Options:
169
170CMake Options
171=============
172
173Here are some of the CMake variables that are used often, along with a
174brief explanation and LLVM-specific notes. For full documentation, check the
175CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
176
177**CMAKE_BUILD_TYPE**:STRING
178 Sets the build type for ``make`` based generators. Possible values are
179 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
180 the user sets the build type with the IDE settings.
181
182**CMAKE_INSTALL_PREFIX**:PATH
183 Path where LLVM will be installed if "make install" is invoked or the
184 "INSTALL" target is built.
185
186**CMAKE_CXX_COMPILER**:STRING
187 The C++ compiler to use when building and testing libc++.
188
189
190.. _libcxx-specific options:
191
192libc++ specific options
193-----------------------
194
Eric Fiselierfa43a5c2016-05-03 22:32:08 +0000195.. option:: LIBCXX_INSTALL_LIBRARY:BOOL
196
197 **Default**: ``ON``
198
199 Toggle the installation of the library portion of libc++.
200
201.. option:: LIBCXX_INSTALL_HEADERS:BOOL
202
203 **Default**: ``ON``
204
205 Toggle the installation of the libc++ headers.
206
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000207.. option:: LIBCXX_ENABLE_ASSERTIONS:BOOL
208
Raul Tambree3f9fa52020-03-30 12:44:15 -0400209 **Default**: ``OFF``
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000210
211 Build libc++ with assertions enabled.
212
213.. option:: LIBCXX_BUILD_32_BITS:BOOL
214
215 **Default**: ``OFF``
216
Eric Fiselier887b86b2016-09-16 03:47:53 +0000217 Build libc++ as a 32 bit library. Also see `LLVM_BUILD_32_BITS`.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000218
219.. option:: LIBCXX_ENABLE_SHARED:BOOL
220
221 **Default**: ``ON``
222
Eric Fiselier887b86b2016-09-16 03:47:53 +0000223 Build libc++ as a shared library. Either `LIBCXX_ENABLE_SHARED` or
224 `LIBCXX_ENABLE_STATIC` has to be enabled.
Petr Hosek13620052016-08-08 22:57:25 +0000225
226.. option:: LIBCXX_ENABLE_STATIC:BOOL
227
228 **Default**: ``ON``
229
Eric Fiselier887b86b2016-09-16 03:47:53 +0000230 Build libc++ as a static library. Either `LIBCXX_ENABLE_SHARED` or
231 `LIBCXX_ENABLE_STATIC` has to be enabled.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000232
233.. option:: LIBCXX_LIBDIR_SUFFIX:STRING
234
235 Extra suffix to append to the directory where libraries are to be installed.
Eric Fiselier887b86b2016-09-16 03:47:53 +0000236 This option overrides `LLVM_LIBDIR_SUFFIX`.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000237
Petr Hosekb42e3492019-01-06 06:14:31 +0000238.. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL
239
240 **Default**: ``OFF``
241
Jonathan Metzmance2328d2019-04-10 23:44:27 +0000242 Do not export any symbols from the static libc++ library.
Petr Hosekb42e3492019-01-06 06:14:31 +0000243 This is useful when the static libc++ library is being linked into shared
244 libraries that may be used in with other shared libraries that use different
Louis Dionned0889672019-08-23 19:42:09 +0000245 C++ library. We want to avoid exporting any libc++ symbols in that case.
Petr Hosekb42e3492019-01-06 06:14:31 +0000246
Eric Fiselier72e2dd82019-03-21 00:04:31 +0000247.. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL
248
249 **Default**: ``ON`` except on Windows.
250
251 This option can be used to enable or disable the filesystem components on
252 platforms that may not support them. For example on Windows.
253
Eric Fiselierfa43a5c2016-05-03 22:32:08 +0000254.. _libc++experimental options:
255
256libc++experimental Specific Options
257------------------------------------
258
259.. option:: LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL
260
261 **Default**: ``ON``
262
263 Build and test libc++experimental.a.
264
265.. option:: LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL
266
Eric Fiselier121594e2016-09-07 01:15:10 +0000267 **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY AND LIBCXX_INSTALL_LIBRARY``
Eric Fiselierfa43a5c2016-05-03 22:32:08 +0000268
269 Install libc++experimental.a alongside libc++.
270
271
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000272.. _ABI Library Specific Options:
273
274ABI Library Specific Options
275----------------------------
276
277.. option:: LIBCXX_CXX_ABI:STRING
278
279 **Values**: ``none``, ``libcxxabi``, ``libcxxrt``, ``libstdc++``, ``libsupc++``.
280
281 Select the ABI library to build libc++ against.
282
283.. option:: LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS
284
285 Provide additional search paths for the ABI library headers.
286
287.. option:: LIBCXX_CXX_ABI_LIBRARY_PATH:PATH
288
289 Provide the path to the ABI library that libc++ should link against.
290
291.. option:: LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL
292
293 **Default**: ``OFF``
294
295 If this option is enabled, libc++ will try and link the selected ABI library
296 statically.
297
Eric Fiselier0b09dd12015-10-15 22:41:51 +0000298.. option:: LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL
299
300 **Default**: ``ON`` by default on UNIX platforms other than Apple unless
301 'LIBCXX_ENABLE_STATIC_ABI_LIBRARY' is ON. Otherwise the default value is ``OFF``.
302
303 This option generate and installs a linker script as ``libc++.so`` which
304 links the correct ABI library.
305
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000306.. option:: LIBCXXABI_USE_LLVM_UNWINDER:BOOL
307
308 **Default**: ``OFF``
309
310 Build and use the LLVM unwinder. Note: This option can only be used when
311 libc++abi is the C++ ABI library used.
312
313
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000314libc++ Feature Options
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000315----------------------
316
317.. option:: LIBCXX_ENABLE_EXCEPTIONS:BOOL
318
319 **Default**: ``ON``
320
321 Build libc++ with exception support.
322
323.. option:: LIBCXX_ENABLE_RTTI:BOOL
324
325 **Default**: ``ON``
326
327 Build libc++ with run time type information.
328
Saleem Abdulrasool1e06a1d2019-07-04 19:08:16 +0000329.. option:: LIBCXX_INCLUDE_TESTS:BOOL
330
Nico Weberf1038c22021-02-18 11:58:48 -0500331 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
Saleem Abdulrasool1e06a1d2019-07-04 19:08:16 +0000332
333 Build the libc++ tests.
334
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000335.. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
Evgeniy Stepanovda2ff7e2015-10-13 23:48:28 +0000336
Eric Fiselier93f212c2016-08-29 19:50:49 +0000337 **Default**: ``ON``
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000338
339 Build the libc++ benchmark tests and the Google Benchmark library needed
340 to support them.
341
Eric Fiselier453bc182018-11-14 20:38:46 +0000342.. option:: LIBCXX_BENCHMARK_TEST_ARGS:STRING
343
344 **Default**: ``--benchmark_min_time=0.01``
345
346 A semicolon list of arguments to pass when running the libc++ benchmarks using the
347 ``check-cxx-benchmarks`` rule. By default we run the benchmarks for a very short amount of time,
348 since the primary use of ``check-cxx-benchmarks`` is to get test and sanitizer coverage, not to
349 get accurate measurements.
350
Eric Fiselier18d2fa32016-10-30 22:53:00 +0000351.. option:: LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000352
Eric Fiselier18d2fa32016-10-30 22:53:00 +0000353 **Default**:: ``""``
354
355 **Values**:: ``libc++``, ``libstdc++``
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000356
357 Build the libc++ benchmark tests and Google Benchmark library against the
Louis Dionneecc89552019-10-01 20:34:50 +0000358 specified standard library on the platform. On Linux this can be used to
Eric Fiselier18d2fa32016-10-30 22:53:00 +0000359 compare libc++ to libstdc++ by building the benchmark tests against both
360 standard libraries.
361
362.. option:: LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING
363
364 Use the specified GCC toolchain and standard library when building the native
365 stdlib benchmark tests.
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000366
Louis Dionne1821de42018-08-16 12:44:28 +0000367.. option:: LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL
368
369 **Default**: ``OFF``
370
371 Pick the default for whether to constrain ABI-unstable symbols to
372 each individual translation unit. This setting controls whether
373 `_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT` is defined by default --
374 see the documentation of that macro for details.
375
Eric Fiselier9e3e1372016-07-19 23:07:03 +0000376
377libc++ ABI Feature Options
378--------------------------
Evgeniy Stepanovda2ff7e2015-10-13 23:48:28 +0000379
380The following options allow building libc++ for a different ABI version.
381
382.. option:: LIBCXX_ABI_VERSION:STRING
383
384 **Default**: ``1``
385
386 Defines the target ABI version of libc++.
387
388.. option:: LIBCXX_ABI_UNSTABLE:BOOL
389
390 **Default**: ``OFF``
391
392 Build the "unstable" ABI version of libc++. Includes all ABI changing features
393 on top of the current stable version.
394
Eric Fiselierb33778a2018-10-30 21:44:53 +0000395.. option:: LIBCXX_ABI_NAMESPACE:STRING
396
397 **Default**: ``__n`` where ``n`` is the current ABI version.
398
399 This option defines the name of the inline ABI versioning namespace. It can be used for building
400 custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
401 with other libc++ versions.
402
403 .. warning::
404 When providing a custom namespace, it's the users responsibility to ensure the name won't cause
Louis Dionne6f2c6fb2018-11-16 14:57:47 +0000405 conflicts with other names defined by libc++, both now and in the future. In particular, inline
406 namespaces of the form ``__[0-9]+`` are strictly reserved by libc++ and may not be used by users.
407 Doing otherwise could cause conflicts and hinder libc++ ABI evolution.
Eric Fiselierb33778a2018-10-30 21:44:53 +0000408
Shoaib Meenai4ca4b7c2017-10-04 23:17:12 +0000409.. option:: LIBCXX_ABI_DEFINES:STRING
410
411 **Default**: ``""``
412
413 A semicolon-separated list of ABI macros to persist in the site config header.
414 See ``include/__config`` for the list of ABI macros.
415
Eric Fiselierf3566292019-05-29 02:21:37 +0000416
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000417.. _LLVM-specific variables:
418
419LLVM-specific options
420---------------------
421
422.. option:: LLVM_LIBDIR_SUFFIX:STRING
423
424 Extra suffix to append to the directory where libraries are to be
425 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
426 to install libraries to ``/usr/lib64``.
427
428.. option:: LLVM_BUILD_32_BITS:BOOL
429
430 Build 32-bits executables and libraries on 64-bits systems. This option is
Louis Dionneecc89552019-10-01 20:34:50 +0000431 available only on some 64-bits Unix systems. Defaults to OFF.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000432
433.. option:: LLVM_LIT_ARGS:STRING
434
435 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
436 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
437 others.
438
439
440Using Alternate ABI libraries
441=============================
442
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400443In order to implement various features like exceptions, RTTI, ``dynamic_cast`` and
444more, libc++ requires what we refer to as an ABI library. Typically, that library
445implements the `Itanium C++ ABI <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000446
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400447By default, libc++ uses libc++abi as an ABI library. However, it is possible to use
448other ABI libraries too.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000449
450Using libsupc++ on Linux
451------------------------
452
453You will need libstdc++ in order to provide libsupc++.
454
455Figure out where the libsupc++ headers are on your system. On Ubuntu this
456is ``/usr/include/c++/<version>`` and ``/usr/include/c++/<version>/<target-triple>``
457
458You can also figure this out by running
459
460.. code-block:: bash
461
462 $ echo | g++ -Wp,-v -x c++ - -fsyntax-only
463 ignoring nonexistent directory "/usr/local/include/x86_64-linux-gnu"
464 ignoring nonexistent directory "/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"
465 #include "..." search starts here:
466 #include &lt;...&gt; search starts here:
467 /usr/include/c++/4.7
468 /usr/include/c++/4.7/x86_64-linux-gnu
469 /usr/include/c++/4.7/backward
470 /usr/lib/gcc/x86_64-linux-gnu/4.7/include
471 /usr/local/include
472 /usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
473 /usr/include/x86_64-linux-gnu
474 /usr/include
475 End of search list.
476
477Note that the first two entries happen to be what we are looking for. This
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400478may not be correct on all platforms.
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000479
480We can now run CMake:
481
482.. code-block:: bash
483
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400484 $ cmake -G Ninja -S llvm -B build \
485 -DLLVM_ENABLE_PROJECTS="libcxx" \
486 -DLIBCXX_CXX_ABI=libstdc++ \
487 -DLIBCXX_CXX_ABI_INCLUDE_PATHS="/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"
488 $ ninja -C build install-cxx
Eric Fiselierd720d1f2015-08-22 19:40:49 +0000489
490
491You can also substitute ``-DLIBCXX_CXX_ABI=libsupc++``
492above, which will cause the library to be linked to libsupc++ instead
493of libstdc++, but this is only recommended if you know that you will
494never need to link against libstdc++ in the same executable as libc++.
495GCC ships libsupc++ separately but only as a static library. If a
496program also needs to link against libstdc++, it will provide its
497own copy of libsupc++ and this can lead to subtle problems.
498
Eric Fiseliera0733922016-06-02 02:16:28 +0000499Using libcxxrt on Linux
500------------------------
501
502You will need to keep the source tree of `libcxxrt`_ available
503on your build machine and your copy of the libcxxrt shared library must
504be placed where your linker will find it.
505
506We can now run CMake like:
507
508.. code-block:: bash
509
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400510 $ cmake -G Ninja -S llvm -B build \
511 -DLLVM_ENABLE_PROJECTS="libcxx" \
512 -DLIBCXX_CXX_ABI=libcxxrt \
513 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/libcxxrt-sources/src
514 $ ninja -C build install-cxx
Eric Fiseliera0733922016-06-02 02:16:28 +0000515
516Unfortunately you can't simply run clang with "-stdlib=libc++" at this point, as
517clang is set up to link for libc++ linked to libsupc++. To get around this
518you'll have to set up your linker yourself (or patch clang). For example,
519
520.. code-block:: bash
521
522 $ clang++ -stdlib=libc++ helloworld.cpp \
523 -nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
524
525Alternately, you could just add libcxxrt to your libraries list, which in most
526situations will give the same result:
527
528.. code-block:: bash
529
530 $ clang++ -stdlib=libc++ helloworld.cpp -lcxxrt
531
Louis Dionne4b1b70d2021-07-06 10:39:01 -0400532.. _`libcxxrt`: https://github.com/libcxxrt/libcxxrt