-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathBuildingLibcxx.html
599 lines (554 loc) · 42.3 KB
/
BuildingLibcxx.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Building libc++ — libc++ 11.0 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Testing libc++" href="TestingLibcxx.html" />
<link rel="prev" title="Using libc++" href="UsingLibcxx.html" />
</head><body>
<div class="header" role="banner"><h1 class="heading"><a href="index.html">
<span>libc++ 11.0 documentation</span></a></h1>
<h2 class="heading"><span>Building libc++</span></h2>
</div>
<div class="topnav" role="navigation" aria-label="top navigation">
<p>
«  <a href="UsingLibcxx.html">Using libc++</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="TestingLibcxx.html">Testing libc++</a>  »
</p>
</div>
<div class="content">
<div class="section" id="building-libc">
<span id="buildinglibcxx"></span><h1>Building libc++<a class="headerlink" href="#building-libc" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#getting-started" id="id3">Getting Started</a><ul>
<li><a class="reference internal" href="#experimental-support-for-windows" id="id4">Experimental Support for Windows</a><ul>
<li><a class="reference internal" href="#cmake-visual-studio" id="id5">CMake + Visual Studio</a></li>
<li><a class="reference internal" href="#cmake-ninja" id="id6">CMake + ninja</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#cmake-options" id="id7">CMake Options</a><ul>
<li><a class="reference internal" href="#libc-specific-options" id="id8">libc++ specific options</a></li>
<li><a class="reference internal" href="#libc-experimental-specific-options" id="id9">libc++experimental Specific Options</a></li>
<li><a class="reference internal" href="#abi-library-specific-options" id="id10">ABI Library Specific Options</a></li>
<li><a class="reference internal" href="#libc-feature-options" id="id11">libc++ Feature Options</a></li>
<li><a class="reference internal" href="#libc-abi-feature-options" id="id12">libc++ ABI Feature Options</a></li>
<li><a class="reference internal" href="#llvm-specific-options" id="id13">LLVM-specific options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-alternate-abi-libraries" id="id14">Using Alternate ABI libraries</a><ul>
<li><a class="reference internal" href="#using-libsupc-on-linux" id="id15">Using libsupc++ on Linux</a></li>
<li><a class="reference internal" href="#using-libcxxrt-on-linux" id="id16">Using libcxxrt on Linux</a></li>
<li><a class="reference internal" href="#using-a-local-abi-library-installation" id="id17">Using a local ABI library installation</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="getting-started">
<span id="build-instructions"></span><h2><a class="toc-backref" href="#id3">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>On Mac OS 10.7 (Lion) and later, the easiest way to get this library is to install
Xcode 4.2 or later. However if you want to install tip-of-trunk from here
(getting the bleeding edge), read on.</p>
<p>The following instructions describe how to checkout, build, test and
(optionally) install libc++ and libc++abi.</p>
<p>If your system already provides a libc++ installation it is important to be
careful not to replace it. Remember Use the CMake option
<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code> to select a safe place to install libc++.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<ul class="last simple">
<li>Replacing your systems libc++ installation could render the system non-functional.</li>
<li>macOS will not boot without a valid copy of <code class="docutils literal notranslate"><span class="pre">libc++.1.dylib</span></code> in <code class="docutils literal notranslate"><span class="pre">/usr/lib</span></code>.</li>
</ul>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/llvm/llvm-project.git
$ <span class="nb">cd</span> llvm-project
$ mkdir build <span class="o">&&</span> <span class="nb">cd</span> build
$ cmake -DCMAKE_C_COMPILER<span class="o">=</span>clang <span class="se">\</span>
-DCMAKE_CXX_COMPILER<span class="o">=</span>clang++ <span class="se">\</span>
-DLLVM_ENABLE_PROJECTS<span class="o">=</span><span class="s2">"libcxx;libcxxabi"</span> <span class="se">\</span>
../llvm
$ make <span class="c1"># Build</span>
$ make check-cxx <span class="c1"># Test</span>
$ make install-cxx install-cxxabi <span class="c1"># Install</span>
</pre></div>
</div>
<p>For more information about configuring libc++ see <a class="reference internal" href="#cmake-options"><span class="std std-ref">CMake Options</span></a>. You may
also want to read the <a class="reference external" href="https://llvm.org/docs/GettingStarted.html">LLVM getting started</a> documentation.</p>
<p>Shared libraries for libc++ and libc++ abi should now be present in
<code class="docutils literal notranslate"><span class="pre">build/lib</span></code>. See <a class="reference internal" href="UsingLibcxx.html#alternate-libcxx"><span class="std std-ref">using an alternate libc++ installation</span></a> for information on how to use this libc++.</p>
<p>The instructions are for building libc++ on
FreeBSD, Linux, or Mac using <a class="reference external" href="http://libcxxabi.llvm.org/">libc++abi</a> as the C++ ABI library.
On Linux, it is also possible to use <a class="reference internal" href="#libsupcxx"><span class="std std-ref">libsupc++</span></a> or libcxxrt.</p>
<p>It is possible to keep your LLVM and libc++ trees separate so you can avoid
rebuilding LLVM as often. An out-of-tree build would look like this:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> where-you-want-libcxx-to-live
$ <span class="c1"># Check out the sources (includes everything, but we'll only use libcxx)</span>
$ <span class="sb">``</span>git clone https://github.com/llvm/llvm-project.git<span class="sb">``</span>
$ <span class="nb">cd</span> where-you-want-to-build
$ mkdir build <span class="o">&&</span> <span class="nb">cd</span> build
$ <span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span>clang <span class="nv">CXX</span><span class="o">=</span>clang++
$ cmake -DLLVM_PATH<span class="o">=</span>path/to/separate/llvm <span class="se">\</span>
-DLIBCXX_CXX_ABI<span class="o">=</span>libcxxabi <span class="se">\</span>
-DLIBCXX_CXX_ABI_INCLUDE_PATHS<span class="o">=</span>path/to/separate/libcxxabi/include <span class="se">\</span>
path/to/llvm-project/libcxx
$ make
$ make check-libcxx <span class="c1"># optional</span>
</pre></div>
</div>
<div class="section" id="experimental-support-for-windows">
<h3><a class="toc-backref" href="#id4">Experimental Support for Windows</a><a class="headerlink" href="#experimental-support-for-windows" title="Permalink to this headline">¶</a></h3>
<p>The Windows support requires building with clang-cl as cl does not support one
required extension: <cite>#include_next</cite>. Furthermore, VS 2015 or newer (19.00) is
required. In the case of clang-cl, we need to specify the “MS Compatibility
Version” as it defaults to 2014 (18.00).</p>
<div class="section" id="cmake-visual-studio">
<h4><a class="toc-backref" href="#id5">CMake + Visual Studio</a><a class="headerlink" href="#cmake-visual-studio" title="Permalink to this headline">¶</a></h4>
<p>Building with Visual Studio currently does not permit running tests. However,
it is the simplest way to build.</p>
<div class="highlight-batch notranslate"><div class="highlight"><pre><span></span><span class="p">></span> cmake -G <span class="s2">"Visual Studio 14 2015"</span> <span class="se">^</span>
<span class="se"> </span> -T <span class="s2">"LLVM-vs2014"</span> <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_SHARED=YES <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_STATIC=NO <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO <span class="se">^</span>
<span class="se"> </span> \path\to\libcxx
<span class="p">></span> cmake --build .
</pre></div>
</div>
</div>
<div class="section" id="cmake-ninja">
<h4><a class="toc-backref" href="#id6">CMake + ninja</a><a class="headerlink" href="#cmake-ninja" title="Permalink to this headline">¶</a></h4>
<p>Building with ninja is required for development to enable tests.
Unfortunately, doing so requires additional configuration as we cannot
just specify a toolset.</p>
<div class="highlight-batch notranslate"><div class="highlight"><pre><span></span><span class="p">></span> cmake -G Ninja <span class="se">^</span>
<span class="se"> </span> -DCMAKE_MAKE_PROGRAM=/path/to/ninja <span class="se">^</span>
<span class="se"> </span> -DCMAKE_SYSTEM_NAME=Windows <span class="se">^</span>
<span class="se"> </span> -DCMAKE_C_COMPILER=clang-cl <span class="se">^</span>
<span class="se"> </span> -DCMAKE_C_FLAGS=<span class="s2">"-fms-compatibility-version=19.00 --target=i686--windows"</span> <span class="se">^</span>
<span class="se"> </span> -DCMAKE_CXX_COMPILER=clang-cl <span class="se">^</span>
<span class="se"> </span> -DCMAKE_CXX_FLAGS=<span class="s2">"-fms-compatibility-version=19.00 --target=i686--windows"</span> <span class="se">^</span>
<span class="se"> </span> -DLLVM_PATH=/path/to/llvm/tree <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_SHARED=YES <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_STATIC=NO <span class="se">^</span>
<span class="se"> </span> -DLIBCXX_ENABLE_EXPERIMENTAL_LIBRARY=NO <span class="se">^</span>
<span class="se"> </span> \path\to\libcxx
<span class="p">></span> /path/to/ninja cxx
<span class="p">></span> /path/to/ninja check-cxx
</pre></div>
</div>
<p>Note that the paths specified with backward slashes must use the <cite>\</cite> as the
directory separator as clang-cl may otherwise parse the path as an argument.</p>
</div>
</div>
</div>
<div class="section" id="cmake-options">
<span id="id1"></span><h2><a class="toc-backref" href="#id7">CMake Options</a><a class="headerlink" href="#cmake-options" title="Permalink to this headline">¶</a></h2>
<p>Here are some of the CMake variables that are used often, along with a
brief explanation and LLVM-specific notes. For full documentation, check the
CMake docs or execute <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--help-variable</span> <span class="pre">VARIABLE_NAME</span></code>.</p>
<dl class="docutils">
<dt><strong>CMAKE_BUILD_TYPE</strong>:STRING</dt>
<dd>Sets the build type for <code class="docutils literal notranslate"><span class="pre">make</span></code> based generators. Possible values are
Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
the user sets the build type with the IDE settings.</dd>
<dt><strong>CMAKE_INSTALL_PREFIX</strong>:PATH</dt>
<dd>Path where LLVM will be installed if “make install” is invoked or the
“INSTALL” target is built.</dd>
<dt><strong>CMAKE_CXX_COMPILER</strong>:STRING</dt>
<dd>The C++ compiler to use when building and testing libc++.</dd>
</dl>
<div class="section" id="libc-specific-options">
<span id="libcxx-specific-options"></span><h3><a class="toc-backref" href="#id8">libc++ specific options</a><a class="headerlink" href="#libc-specific-options" title="Permalink to this headline">¶</a></h3>
<dl class="option">
<dt id="cmdoption-arg-libcxx-install-library-bool">
<code class="descname">LIBCXX_INSTALL_LIBRARY:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-install-library-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Toggle the installation of the library portion of libc++.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-install-headers-bool">
<code class="descname">LIBCXX_INSTALL_HEADERS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-install-headers-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Toggle the installation of the libc++ headers.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-assertions-bool">
<code class="descname">LIBCXX_ENABLE_ASSERTIONS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-assertions-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build libc++ with assertions enabled.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-build-32-bits-bool">
<code class="descname">LIBCXX_BUILD_32_BITS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-build-32-bits-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>Build libc++ as a 32 bit library. Also see <cite>LLVM_BUILD_32_BITS</cite>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-shared-bool">
<code class="descname">LIBCXX_ENABLE_SHARED:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-shared-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build libc++ as a shared library. Either <cite>LIBCXX_ENABLE_SHARED</cite> or
<cite>LIBCXX_ENABLE_STATIC</cite> has to be enabled.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-static-bool">
<code class="descname">LIBCXX_ENABLE_STATIC:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-static-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build libc++ as a static library. Either <cite>LIBCXX_ENABLE_SHARED</cite> or
<cite>LIBCXX_ENABLE_STATIC</cite> has to be enabled.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-libdir-suffix-string">
<code class="descname">LIBCXX_LIBDIR_SUFFIX:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-libdir-suffix-string" title="Permalink to this definition">¶</a></dt>
<dd><p>Extra suffix to append to the directory where libraries are to be installed.
This option overrides <cite>LLVM_LIBDIR_SUFFIX</cite>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-install-prefix-string">
<code class="descname">LIBCXX_INSTALL_PREFIX:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-install-prefix-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">""</span></code></p>
<p>Define libc++ destination prefix.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-hermetic-static-library-bool">
<code class="descname">LIBCXX_HERMETIC_STATIC_LIBRARY:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-hermetic-static-library-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>Do not export any symbols from the static libc++ library.
This is useful when the static libc++ library is being linked into shared
libraries that may be used in with other shared libraries that use different
C++ library. We want to avoid exporting any libc++ symbols in that case.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-filesystem-bool">
<code class="descname">LIBCXX_ENABLE_FILESYSTEM:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-filesystem-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code> except on Windows.</p>
<p>This option can be used to enable or disable the filesystem components on
platforms that may not support them. For example on Windows.</p>
</dd></dl>
</div>
<div class="section" id="libc-experimental-specific-options">
<span id="libc-experimental-options"></span><h3><a class="toc-backref" href="#id9">libc++experimental Specific Options</a><a class="headerlink" href="#libc-experimental-specific-options" title="Permalink to this headline">¶</a></h3>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-experimental-library-bool">
<code class="descname">LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-experimental-library-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build and test libc++experimental.a.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-install-experimental-library-bool">
<code class="descname">LIBCXX_INSTALL_EXPERIMENTAL_LIBRARY:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-install-experimental-library-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY</span> <span class="pre">AND</span> <span class="pre">LIBCXX_INSTALL_LIBRARY</span></code></p>
<p>Install libc++experimental.a alongside libc++.</p>
</dd></dl>
</div>
<div class="section" id="abi-library-specific-options">
<span id="id2"></span><h3><a class="toc-backref" href="#id10">ABI Library Specific Options</a><a class="headerlink" href="#abi-library-specific-options" title="Permalink to this headline">¶</a></h3>
<dl class="option">
<dt id="cmdoption-arg-libcxx-cxx-abi-string">
<code class="descname">LIBCXX_CXX_ABI:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-cxx-abi-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Values</strong>: <code class="docutils literal notranslate"><span class="pre">none</span></code>, <code class="docutils literal notranslate"><span class="pre">libcxxabi</span></code>, <code class="docutils literal notranslate"><span class="pre">libcxxrt</span></code>, <code class="docutils literal notranslate"><span class="pre">libstdc++</span></code>, <code class="docutils literal notranslate"><span class="pre">libsupc++</span></code>.</p>
<p>Select the ABI library to build libc++ against.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-cxx-abi-include-paths-paths">
<code class="descname">LIBCXX_CXX_ABI_INCLUDE_PATHS:PATHS</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-cxx-abi-include-paths-paths" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide additional search paths for the ABI library headers.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-cxx-abi-library-path-path">
<code class="descname">LIBCXX_CXX_ABI_LIBRARY_PATH:PATH</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-cxx-abi-library-path-path" title="Permalink to this definition">¶</a></dt>
<dd><p>Provide the path to the ABI library that libc++ should link against.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-static-abi-library-bool">
<code class="descname">LIBCXX_ENABLE_STATIC_ABI_LIBRARY:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-static-abi-library-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>If this option is enabled, libc++ will try and link the selected ABI library
statically.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-abi-linker-script-bool">
<code class="descname">LIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-abi-linker-script-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code> by default on UNIX platforms other than Apple unless
‘LIBCXX_ENABLE_STATIC_ABI_LIBRARY’ is ON. Otherwise the default value is <code class="docutils literal notranslate"><span class="pre">OFF</span></code>.</p>
<p>This option generate and installs a linker script as <code class="docutils literal notranslate"><span class="pre">libc++.so</span></code> which
links the correct ABI library.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxxabi-use-llvm-unwinder-bool">
<code class="descname">LIBCXXABI_USE_LLVM_UNWINDER:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxxabi-use-llvm-unwinder-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>Build and use the LLVM unwinder. Note: This option can only be used when
libc++abi is the C++ ABI library used.</p>
</dd></dl>
</div>
<div class="section" id="libc-feature-options">
<h3><a class="toc-backref" href="#id11">libc++ Feature Options</a><a class="headerlink" href="#libc-feature-options" title="Permalink to this headline">¶</a></h3>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-exceptions-bool">
<code class="descname">LIBCXX_ENABLE_EXCEPTIONS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-exceptions-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build libc++ with exception support.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-enable-rtti-bool">
<code class="descname">LIBCXX_ENABLE_RTTI:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-enable-rtti-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build libc++ with run time type information.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-include-tests-bool">
<code class="descname">LIBCXX_INCLUDE_TESTS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-include-tests-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code> (or value of <code class="docutils literal notranslate"><span class="pre">LLVM_INCLUDE_DIR</span></code>)</p>
<p>Build the libc++ tests.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-include-benchmarks-bool">
<code class="descname">LIBCXX_INCLUDE_BENCHMARKS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-include-benchmarks-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">ON</span></code></p>
<p>Build the libc++ benchmark tests and the Google Benchmark library needed
to support them.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-benchmark-test-args-string">
<code class="descname">LIBCXX_BENCHMARK_TEST_ARGS:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-benchmark-test-args-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">--benchmark_min_time=0.01</span></code></p>
<p>A semicolon list of arguments to pass when running the libc++ benchmarks using the
<code class="docutils literal notranslate"><span class="pre">check-cxx-benchmarks</span></code> rule. By default we run the benchmarks for a very short amount of time,
since the primary use of <code class="docutils literal notranslate"><span class="pre">check-cxx-benchmarks</span></code> is to get test and sanitizer coverage, not to
get accurate measurements.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-benchmark-native-stdlib-string">
<code class="descname">LIBCXX_BENCHMARK_NATIVE_STDLIB:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-benchmark-native-stdlib-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>:: <code class="docutils literal notranslate"><span class="pre">""</span></code></p>
<p><strong>Values</strong>:: <code class="docutils literal notranslate"><span class="pre">libc++</span></code>, <code class="docutils literal notranslate"><span class="pre">libstdc++</span></code></p>
<p>Build the libc++ benchmark tests and Google Benchmark library against the
specified standard library on the platform. On Linux this can be used to
compare libc++ to libstdc++ by building the benchmark tests against both
standard libraries.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-benchmark-native-gcc-toolchain-string">
<code class="descname">LIBCXX_BENCHMARK_NATIVE_GCC_TOOLCHAIN:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-benchmark-native-gcc-toolchain-string" title="Permalink to this definition">¶</a></dt>
<dd><p>Use the specified GCC toolchain and standard library when building the native
stdlib benchmark tests.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-hide-from-abi-per-tu-by-default-bool">
<code class="descname">LIBCXX_HIDE_FROM_ABI_PER_TU_BY_DEFAULT:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-hide-from-abi-per-tu-by-default-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>Pick the default for whether to constrain ABI-unstable symbols to
each individual translation unit. This setting controls whether
<cite>_LIBCPP_HIDE_FROM_ABI_PER_TU_BY_DEFAULT</cite> is defined by default –
see the documentation of that macro for details.</p>
</dd></dl>
</div>
<div class="section" id="libc-abi-feature-options">
<h3><a class="toc-backref" href="#id12">libc++ ABI Feature Options</a><a class="headerlink" href="#libc-abi-feature-options" title="Permalink to this headline">¶</a></h3>
<p>The following options allow building libc++ for a different ABI version.</p>
<dl class="option">
<dt id="cmdoption-arg-libcxx-abi-version-string">
<code class="descname">LIBCXX_ABI_VERSION:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-abi-version-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">1</span></code></p>
<p>Defines the target ABI version of libc++.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-abi-unstable-bool">
<code class="descname">LIBCXX_ABI_UNSTABLE:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-abi-unstable-bool" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">OFF</span></code></p>
<p>Build the “unstable” ABI version of libc++. Includes all ABI changing features
on top of the current stable version.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-abi-namespace-string">
<code class="descname">LIBCXX_ABI_NAMESPACE:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-abi-namespace-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">__n</span></code> where <code class="docutils literal notranslate"><span class="pre">n</span></code> is the current ABI version.</p>
<p>This option defines the name of the inline ABI versioning namespace. It can be used for building
custom versions of libc++ with unique symbol names in order to prevent conflicts or ODR issues
with other libc++ versions.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When providing a custom namespace, it’s the users responsibility to ensure the name won’t cause
conflicts with other names defined by libc++, both now and in the future. In particular, inline
namespaces of the form <code class="docutils literal notranslate"><span class="pre">__[0-9]+</span></code> are strictly reserved by libc++ and may not be used by users.
Doing otherwise could cause conflicts and hinder libc++ ABI evolution.</p>
</div>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-abi-defines-string">
<code class="descname">LIBCXX_ABI_DEFINES:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-abi-defines-string" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">""</span></code></p>
<p>A semicolon-separated list of ABI macros to persist in the site config header.
See <code class="docutils literal notranslate"><span class="pre">include/__config</span></code> for the list of ABI macros.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-libcxx-has-merged-typeinfo-names-default">
<code class="descname">LIBCXX_HAS_MERGED_TYPEINFO_NAMES_DEFAULT</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-libcxx-has-merged-typeinfo-names-default" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>Default</strong>: <code class="docutils literal notranslate"><span class="pre">None</span></code>. When defined this option overrides the libraries default configuration
for whether merged type info names are present.</p>
<p>Build <code class="docutils literal notranslate"><span class="pre">std::type_info</span></code> with the assumption that type info names for a type have been fully
merged are unique across the entire program. This may not be the case for libraries built with
<code class="docutils literal notranslate"><span class="pre">-Bsymbolic</span></code> or due to compiler or linker bugs (Ex. llvm.org/PR37398).</p>
<p>When the value is <code class="docutils literal notranslate"><span class="pre">ON</span></code> typeinfo comparisons compare only the pointer value, otherwise <code class="docutils literal notranslate"><span class="pre">strcmp</span></code>
is used as a fallback.</p>
</dd></dl>
</div>
<div class="section" id="llvm-specific-options">
<span id="llvm-specific-variables"></span><h3><a class="toc-backref" href="#id13">LLVM-specific options</a><a class="headerlink" href="#llvm-specific-options" title="Permalink to this headline">¶</a></h3>
<dl class="option">
<dt id="cmdoption-arg-llvm-libdir-suffix-string">
<code class="descname">LLVM_LIBDIR_SUFFIX:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-llvm-libdir-suffix-string" title="Permalink to this definition">¶</a></dt>
<dd><p>Extra suffix to append to the directory where libraries are to be
installed. On a 64-bit architecture, one could use <code class="docutils literal notranslate"><span class="pre">-DLLVM_LIBDIR_SUFFIX=64</span></code>
to install libraries to <code class="docutils literal notranslate"><span class="pre">/usr/lib64</span></code>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-llvm-build-32-bits-bool">
<code class="descname">LLVM_BUILD_32_BITS:BOOL</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-llvm-build-32-bits-bool" title="Permalink to this definition">¶</a></dt>
<dd><p>Build 32-bits executables and libraries on 64-bits systems. This option is
available only on some 64-bits Unix systems. Defaults to OFF.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-arg-llvm-lit-args-string">
<code class="descname">LLVM_LIT_ARGS:STRING</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-llvm-lit-args-string" title="Permalink to this definition">¶</a></dt>
<dd><p>Arguments given to lit. <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check</span></code> and <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clang-test</span></code> are affected.
By default, <code class="docutils literal notranslate"><span class="pre">'-sv</span> <span class="pre">--no-progress-bar'</span></code> on Visual C++ and Xcode, <code class="docutils literal notranslate"><span class="pre">'-sv'</span></code> on
others.</p>
</dd></dl>
</div>
</div>
<div class="section" id="using-alternate-abi-libraries">
<h2><a class="toc-backref" href="#id14">Using Alternate ABI libraries</a><a class="headerlink" href="#using-alternate-abi-libraries" title="Permalink to this headline">¶</a></h2>
<div class="section" id="using-libsupc-on-linux">
<span id="libsupcxx"></span><h3><a class="toc-backref" href="#id15">Using libsupc++ on Linux</a><a class="headerlink" href="#using-libsupc-on-linux" title="Permalink to this headline">¶</a></h3>
<p>You will need libstdc++ in order to provide libsupc++.</p>
<p>Figure out where the libsupc++ headers are on your system. On Ubuntu this
is <code class="docutils literal notranslate"><span class="pre">/usr/include/c++/<version></span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/include/c++/<version>/<target-triple></span></code></p>
<p>You can also figure this out by running</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">echo</span> <span class="p">|</span> g++ -Wp,-v -x c++ - -fsyntax-only
ignoring nonexistent directory <span class="s2">"/usr/local/include/x86_64-linux-gnu"</span>
ignoring nonexistent directory <span class="s2">"/usr/lib/gcc/x86_64-linux-gnu/4.7/../../../../x86_64-linux-gnu/include"</span>
<span class="c1">#include "..." search starts here:</span>
<span class="c1">#include &lt;...&gt; search starts here:</span>
/usr/include/c++/4.7
/usr/include/c++/4.7/x86_64-linux-gnu
/usr/include/c++/4.7/backward
/usr/lib/gcc/x86_64-linux-gnu/4.7/include
/usr/local/include
/usr/lib/gcc/x86_64-linux-gnu/4.7/include-fixed
/usr/include/x86_64-linux-gnu
/usr/include
End of search list.
</pre></div>
</div>
<p>Note that the first two entries happen to be what we are looking for. This
may not be correct on other platforms.</p>
<p>We can now run CMake:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">CC</span><span class="o">=</span>clang <span class="nv">CXX</span><span class="o">=</span>clang++ cmake -G <span class="s2">"Unix Makefiles"</span> <span class="se">\</span>
-DLIBCXX_CXX_ABI<span class="o">=</span>libstdc++ <span class="se">\</span>
-DLIBCXX_CXX_ABI_INCLUDE_PATHS<span class="o">=</span><span class="s2">"/usr/include/c++/4.7/;/usr/include/c++/4.7/x86_64-linux-gnu/"</span> <span class="se">\</span>
-DCMAKE_BUILD_TYPE<span class="o">=</span>Release -DCMAKE_INSTALL_PREFIX<span class="o">=</span>/usr <span class="se">\</span>
<libc++-source-dir>
</pre></div>
</div>
<p>You can also substitute <code class="docutils literal notranslate"><span class="pre">-DLIBCXX_CXX_ABI=libsupc++</span></code>
above, which will cause the library to be linked to libsupc++ instead
of libstdc++, but this is only recommended if you know that you will
never need to link against libstdc++ in the same executable as libc++.
GCC ships libsupc++ separately but only as a static library. If a
program also needs to link against libstdc++, it will provide its
own copy of libsupc++ and this can lead to subtle problems.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ make cxx
$ make install
</pre></div>
</div>
<p>You can now run clang with -stdlib=libc++.</p>
</div>
<div class="section" id="using-libcxxrt-on-linux">
<span id="libcxxrt-ref"></span><h3><a class="toc-backref" href="#id16">Using libcxxrt on Linux</a><a class="headerlink" href="#using-libcxxrt-on-linux" title="Permalink to this headline">¶</a></h3>
<p>You will need to keep the source tree of <a class="reference external" href="https://github.com/pathscale/libcxxrt/">libcxxrt</a> available
on your build machine and your copy of the libcxxrt shared library must
be placed where your linker will find it.</p>
<p>We can now run CMake like:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">CC</span><span class="o">=</span>clang <span class="nv">CXX</span><span class="o">=</span>clang++ cmake -G <span class="s2">"Unix Makefiles"</span> <span class="se">\</span>
-DLIBCXX_CXX_ABI<span class="o">=</span>libcxxrt <span class="se">\</span>
-DLIBCXX_CXX_ABI_INCLUDE_PATHS<span class="o">=</span>path/to/libcxxrt-sources/src <span class="se">\</span>
-DCMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
-DCMAKE_INSTALL_PREFIX<span class="o">=</span>/usr <span class="se">\</span>
<libc++-source-directory>
$ make cxx
$ make install
</pre></div>
</div>
<p>Unfortunately you can’t simply run clang with “-stdlib=libc++” at this point, as
clang is set up to link for libc++ linked to libsupc++. To get around this
you’ll have to set up your linker yourself (or patch clang). For example,</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ helloworld.cpp <span class="se">\</span>
-nodefaultlibs -lc++ -lcxxrt -lm -lc -lgcc_s -lgcc
</pre></div>
</div>
<p>Alternately, you could just add libcxxrt to your libraries list, which in most
situations will give the same result:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang++ -stdlib<span class="o">=</span>libc++ helloworld.cpp -lcxxrt
</pre></div>
</div>
</div>
<div class="section" id="using-a-local-abi-library-installation">
<h3><a class="toc-backref" href="#id17">Using a local ABI library installation</a><a class="headerlink" href="#using-a-local-abi-library-installation" title="Permalink to this headline">¶</a></h3>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This is not recommended in almost all cases.</p>
</div>
<p>These instructions should only be used when you can’t install your ABI library.</p>
<p>Normally you must link libc++ against a ABI shared library that the
linker can find. If you want to build and test libc++ against an ABI
library not in the linker’s path you need to set
<code class="docutils literal notranslate"><span class="pre">-DLIBCXX_CXX_ABI_LIBRARY_PATH=/path/to/abi/lib</span></code> when configuring CMake.</p>
<p>An example build using libc++abi would look like:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">CC</span><span class="o">=</span>clang <span class="nv">CXX</span><span class="o">=</span>clang++ cmake <span class="se">\</span>
-DLIBCXX_CXX_ABI<span class="o">=</span>libc++abi <span class="se">\</span>
-DLIBCXX_CXX_ABI_INCLUDE_PATHS<span class="o">=</span><span class="s2">"/path/to/libcxxabi/include"</span> <span class="se">\</span>
-DLIBCXX_CXX_ABI_LIBRARY_PATH<span class="o">=</span><span class="s2">"/path/to/libcxxabi-build/lib"</span> <span class="se">\</span>
path/to/libcxx
$ make
</pre></div>
</div>
<p>When testing libc++ LIT will automatically link against the proper ABI
library.</p>
</div>
</div>
</div>
</div>
<div class="bottomnav" role="navigation" aria-label="bottom navigation">
<p>
«  <a href="UsingLibcxx.html">Using libc++</a>
  ::  
<a class="uplink" href="index.html">Contents</a>
  ::  
<a href="TestingLibcxx.html">Testing libc++</a>  »
</p>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2018, LLVM Project.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>