Mercurial > hg > CbC > CbC_llvm

comparison libcxx/docs/BuildingLibcxx.rst @ 221:79ff65ed7e25

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LLVM12 Original
author Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date Tue, 15 Jun 2021 19:15:29 +0900
parents 0572611fdcc8
children 5f17cb93ff66
comparison
equal deleted inserted replaced
220:42394fc6a535 221:79ff65ed7e25
50 50
51 The instructions are for building libc++ on 51 The instructions are for building libc++ on
52 FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library. 52 FreeBSD, Linux, or Mac using `libc++abi`_ as the C++ ABI library.
53 On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt. 53 On Linux, it is also possible to use :ref:`libsupc++ <libsupcxx>` or libcxxrt.
54 54
55 It is possible to keep your LLVM and libc++ trees separate so you can avoid 55 It is possible to build libc++ standalone (i.e. without building other LLVM
56 rebuilding LLVM as often. An out-of-tree build would look like this: 56 projects). A standalone build would look like this:
57 57
58 .. code-block:: bash 58 .. code-block:: bash
59 59
60 $ cd where-you-want-libcxx-to-live 60 $ git clone https://github.com/llvm/llvm-project.git llvm-project
61 $ # Check out the sources (includes everything, but we'll only use libcxx) 61 $ cd llvm-project
62 $ ``git clone https://github.com/llvm/llvm-project.git``
63 $ cd where-you-want-to-build
64 $ mkdir build && cd build 62 $ mkdir build && cd build
65 $ export CC=clang CXX=clang++ 63 $ cmake -DCMAKE_C_COMPILER=clang \
66 $ cmake -DLLVM_PATH=path/to/separate/llvm \ 64 -DCMAKE_CXX_COMPILER=clang++ \
67 -DLIBCXX_CXX_ABI=libcxxabi \ 65 -DLIBCXX_CXX_ABI=libcxxabi \
68 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/separate/libcxxabi/include \ 66 -DLIBCXX_CXX_ABI_INCLUDE_PATHS=path/to/separate/libcxxabi/include \
69 path/to/llvm-project/libcxx 67 ../libcxx
70 $ make 68 $ make
71 $ make check-cxx # optional 69 $ make check-cxx # optional
72 70
73 71
74 Experimental Support for Windows 72 Support for Windows
75 -------------------------------- 73 -------------------
76 74
77 The Windows support requires building with clang-cl as cl does not support one 75 libcxx supports being built with clang-cl, but not with MSVC's cl.exe, as
78 required extension: `#include_next`. Furthermore, VS 2015 or newer (19.00) is 76 cl doesn't support the ``#include_next`` extension. Furthermore, VS 2017 or
79 required. In the case of clang-cl, we need to specify the "MS Compatibility 77 newer (19.14) is required.
80 Version" as it defaults to 2014 (18.00). 78
79 libcxx also supports being built with clang targeting MinGW environments.
81 80
82 CMake + Visual Studio 81 CMake + Visual Studio
83 ~~~~~~~~~~~~~~~~~~~~~ 82 ~~~~~~~~~~~~~~~~~~~~~
84 83
85 Building with Visual Studio currently does not permit running tests. However, 84 Building with Visual Studio currently does not permit running tests. However,
86 it is the simplest way to build. 85 it is the simplest way to build.
87 86
88 .. code-block:: batch 87 .. code-block:: batch
89 88
90 > cmake -G "Visual Studio 14 2015" ^ 89 > cmake -G "Visual Studio 16 2019" ^
91 -T "LLVM-vs2014" ^ 90 -T "ClangCL" ^
92 -DLIBCXX_ENABLE_SHARED=YES ^ 91 -DLIBCXX_ENABLE_SHARED=YES ^
93 -DLIBCXX_ENABLE_STATIC=NO ^ 92 -DLIBCXX_ENABLE_STATIC=NO ^
94 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ 93 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
95 \path\to\libcxx 94 \path\to\libcxx
96 > cmake --build . 95 > cmake --build .
97 96
98 CMake + ninja 97 CMake + ninja (MSVC)
99 ~~~~~~~~~~~~~ 98 ~~~~~~~~~~~~~~~~~~~~
100 99
101 Building with ninja is required for development to enable tests. 100 Building with ninja is required for development to enable tests.
102 Unfortunately, doing so requires additional configuration as we cannot 101 A couple of tests require Bash to be available, and a couple dozens
103 just specify a toolset. 102 of tests require other posix tools (cp, grep and similar - LLVM's tests
103 require the same). Without those tools the vast majority of tests
104 can still be ran successfully.
105
106 If Git for Windows is available, that can be used to provide the bash
107 shell by adding the right bin directory to the path, e.g.
108 ``set PATH=%PATH%;C:\Program Files\Git\usr\bin``.
109
110 Alternatively, one can also choose to run the whole build in a MSYS2
111 shell. That can be set up e.g. by starting a Visual Studio Tools Command
112 Prompt (for getting the environment variables pointing to the headers and
113 import libraries), and making sure that clang-cl is available in the
114 path. From there, launch an MSYS2 shell via e.g.
115 ``C:\msys64\msys2_shell.cmd -full-path -mingw64`` (preserving the earlier
116 environment, allowing the MSVC headers/libraries and clang-cl to be found).
117
118 In either case, then run:
104 119
105 .. code-block:: batch 120 .. code-block:: batch
106 121
107 > cmake -G Ninja ^ 122 > cmake -G Ninja ^
108 -DCMAKE_MAKE_PROGRAM=/path/to/ninja ^ 123 -DCMAKE_BUILD_TYPE=Release ^
109 -DCMAKE_SYSTEM_NAME=Windows ^
110 -DCMAKE_C_COMPILER=clang-cl ^ 124 -DCMAKE_C_COMPILER=clang-cl ^
111 -DCMAKE_C_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^ 125 -DCMAKE_CXX_COMPILER=clang-cl ^
112 -DCMAKE_CXX_COMPILER=clang-cl ^
113 -DCMAKE_CXX_FLAGS="-fms-compatibility-version=19.00 --target=i686--windows" ^
114 -DLLVM_PATH=/path/to/llvm/tree ^
115 -DLIBCXX_ENABLE_SHARED=YES ^
116 -DLIBCXX_ENABLE_STATIC=NO ^
117 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^ 126 -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO ^
118 \path\to\libcxx 127 path/to/libcxx
119 > /path/to/ninja cxx 128 > ninja cxx
120 > /path/to/ninja check-cxx 129 > ninja check-cxx
121 130
122 Note that the paths specified with backward slashes must use the `\\` as the 131 If you are running in an MSYS2 shell and you have installed the
123 directory separator as clang-cl may otherwise parse the path as an argument. 132 MSYS2-provided clang package (which defaults to a non-MSVC target), you
133 should add e.g. ``-DLIBCXX_TARGET_TRIPLE=x86_64-windows-msvc`` (replacing
134 ``x86_64`` with the architecture you're targeting) to the ``cmake`` command
135 line above. This will instruct ``check-cxx`` to use the right target triple
136 when invoking ``clang++``.
137
138 Also note that if not building in Release mode, a failed assert in the tests
139 pops up a blocking dialog box, making it hard to run a larger number of tests.
140
141 CMake + ninja (MinGW)
142 ~~~~~~~~~~~~~~~~~~~~~
143
144 libcxx can also be built in MinGW environments, e.g. with the MinGW
145 compilers in MSYS2. This requires clang to be available (installed with
146 e.g. the ``mingw-w64-x86_64-clang`` package), together with CMake and ninja.
147
148 .. code-block:: bash
149
150 > cmake -G Ninja \
151 -DCMAKE_C_COMPILER=clang \
152 -DCMAKE_CXX_COMPILER=clang++ \
153 -DLIBCXX_HAS_WIN32_THREAD_API=ON \
154 -DLIBCXX_CXX_ABI=libstdc++ \
155 -DLIBCXX_TARGET_INFO="libcxx.test.target_info.MingwLocalTI" \
156 path/to/libcxx
157 > ninja cxx
158 > cp /mingw64/bin/{libstdc++-6,libgcc_s_seh-1,libwinpthread-1}.dll lib
159 > ninja check-cxx
160
161 As this build configuration ends up depending on a couple other DLLs that
162 aren't available in path while running tests, copy them into the same
163 directory as the tested libc++ DLL.
164
165 (Building a libc++ that depends on libstdc++ isn't necessarily a config one
166 would want to deploy, but it simplifies the config for testing purposes.)
124 167
125 .. _`libc++abi`: http://libcxxabi.llvm.org/ 168 .. _`libc++abi`: http://libcxxabi.llvm.org/
126 169
127 170
128 .. _CMake Options: 171 .. _CMake Options:
193 .. option:: LIBCXX_LIBDIR_SUFFIX:STRING 236 .. option:: LIBCXX_LIBDIR_SUFFIX:STRING
194 237
195 Extra suffix to append to the directory where libraries are to be installed. 238 Extra suffix to append to the directory where libraries are to be installed.
196 This option overrides `LLVM_LIBDIR_SUFFIX`. 239 This option overrides `LLVM_LIBDIR_SUFFIX`.
197 240
198 .. option:: LIBCXX_INSTALL_PREFIX:STRING
199
200 **Default**: ``""``
201
202 Define libc++ destination prefix.
203
204 .. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL 241 .. option:: LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL
205 242
206 **Default**: ``OFF`` 243 **Default**: ``OFF``
207 244
208 Do not export any symbols from the static libc++ library. 245 Do not export any symbols from the static libc++ library.
292 329
293 Build libc++ with run time type information. 330 Build libc++ with run time type information.
294 331
295 .. option:: LIBCXX_INCLUDE_TESTS:BOOL 332 .. option:: LIBCXX_INCLUDE_TESTS:BOOL
296 333
297 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_DIR``) 334 **Default**: ``ON`` (or value of ``LLVM_INCLUDE_TESTS``)
298 335
299 Build the libc++ tests. 336 Build the libc++ tests.
300 337
301 .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL 338 .. option:: LIBCXX_INCLUDE_BENCHMARKS:BOOL
302 339
376 413
377 **Default**: ``""`` 414 **Default**: ``""``
378 415
379 A semicolon-separated list of ABI macros to persist in the site config header. 416 A semicolon-separated list of ABI macros to persist in the site config header.
380 See ``include/__config`` for the list of ABI macros. 417 See ``include/__config`` for the list of ABI macros.
381
382
383 .. option:: LIBCXX_HAS_MERGED_TYPEINFO_NAMES_DEFAULT
384
385 **Default**: ``None``. When defined this option overrides the libraries default configuration
386 for whether merged type info names are present.
387
388
389 Build ``std::type_info`` with the assumption that type info names for a type have been fully
390 merged are unique across the entire program. This may not be the case for libraries built with
391 ``-Bsymbolic`` or due to compiler or linker bugs (Ex. llvm.org/PR37398).
392
393 When the value is ``ON`` typeinfo comparisons compare only the pointer value, otherwise ``strcmp``
394 is used as a fallback.
395 418
396 419
397 .. _LLVM-specific variables: 420 .. _LLVM-specific variables:
398 421
399 LLVM-specific options 422 LLVM-specific options