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
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting Started with the LLVM System — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
<link rel="prev" title="Performance Tips for Frontend Authors" href="Frontend/PerformanceTips.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingStartedTutorials.html" accesskey="U">Getting Started/Tutorials</a> »</li>
<li class="nav-item nav-item-this"><a href="">Getting Started with the LLVM System</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/GettingStarted.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="getting-started-with-the-llvm-system">
<h1>Getting Started with the LLVM System<a class="headerlink" href="#getting-started-with-the-llvm-system" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#overview" id="id4">Overview</a></p></li>
<li><p><a class="reference internal" href="#getting-the-source-code-and-building-llvm" id="id5">Getting the Source Code and Building LLVM</a></p></li>
<li><p><a class="reference internal" href="#requirements" id="id6">Requirements</a></p>
<ul>
<li><p><a class="reference internal" href="#hardware" id="id7">Hardware</a></p></li>
<li><p><a class="reference internal" href="#software" id="id8">Software</a></p></li>
<li><p><a class="reference internal" href="#host-c-toolchain-both-compiler-and-standard-library" id="id9">Host C++ Toolchain, both Compiler and Standard Library</a></p>
<ul>
<li><p><a class="reference internal" href="#getting-a-modern-host-c-toolchain" id="id10">Getting a Modern Host C++ Toolchain</a></p></li>
</ul>
</li>
</ul>
</li>
<li><p><a class="reference internal" href="#getting-started-with-llvm" id="id11">Getting Started with LLVM</a></p>
<ul>
<li><p><a class="reference internal" href="#terminology-and-notation" id="id12">Terminology and Notation</a></p></li>
<li><p><a class="reference internal" href="#unpacking-the-llvm-archives" id="id13">Unpacking the LLVM Archives</a></p></li>
<li><p><a class="reference internal" href="#checkout-llvm-from-git" id="id14">Checkout LLVM from Git</a></p>
<ul>
<li><p><a class="reference internal" href="#sending-patches" id="id15">Sending patches</a></p></li>
<li><p><a class="reference internal" href="#for-developers-to-commit-changes-from-git" id="id16">For developers to commit changes from Git</a></p></li>
<li><p><a class="reference internal" href="#git-pre-push-hook" id="id17">Git pre-push hook</a></p></li>
<li><p><a class="reference internal" href="#bisecting-commits" id="id18">Bisecting commits</a></p></li>
<li><p><a class="reference internal" href="#reverting-a-change" id="id19">Reverting a change</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#local-llvm-configuration" id="id20">Local LLVM Configuration</a></p></li>
<li><p><a class="reference internal" href="#compiling-the-llvm-suite-source-code" id="id21">Compiling the LLVM Suite Source Code</a></p></li>
<li><p><a class="reference internal" href="#cross-compiling-llvm" id="id22">Cross-Compiling LLVM</a></p></li>
<li><p><a class="reference internal" href="#the-location-of-llvm-object-files" id="id23">The Location of LLVM Object Files</a></p></li>
<li><p><a class="reference internal" href="#optional-configuration-items" id="id24">Optional Configuration Items</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#directory-layout" id="id25">Directory Layout</a></p>
<ul>
<li><p><a class="reference internal" href="#llvm-cmake" id="id26"><code class="docutils literal notranslate"><span class="pre">llvm/cmake</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-examples" id="id27"><code class="docutils literal notranslate"><span class="pre">llvm/examples</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-include" id="id28"><code class="docutils literal notranslate"><span class="pre">llvm/include</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-lib" id="id29"><code class="docutils literal notranslate"><span class="pre">llvm/lib</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-bindings" id="id30"><code class="docutils literal notranslate"><span class="pre">llvm/bindings</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-projects" id="id31"><code class="docutils literal notranslate"><span class="pre">llvm/projects</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-test" id="id32"><code class="docutils literal notranslate"><span class="pre">llvm/test</span></code></a></p></li>
<li><p><a class="reference internal" href="#test-suite" id="id33"><code class="docutils literal notranslate"><span class="pre">test-suite</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-tools" id="id34"><code class="docutils literal notranslate"><span class="pre">llvm/tools</span></code></a></p></li>
<li><p><a class="reference internal" href="#llvm-utils" id="id35"><code class="docutils literal notranslate"><span class="pre">llvm/utils</span></code></a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#an-example-using-the-llvm-tool-chain" id="id36">An Example Using the LLVM Tool Chain</a></p>
<ul>
<li><p><a class="reference internal" href="#example-with-clang" id="id37">Example with clang</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#common-problems" id="id38">Common Problems</a></p></li>
<li><p><a class="reference internal" href="#links" id="id39">Links</a></p></li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id4">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Welcome to the LLVM project!</p>
<p>The LLVM project has multiple components. The core of the project is
itself called “LLVM”. This contains all of the tools, libraries, and header
files needed to process intermediate representations and converts it into
object files. Tools include an assembler, disassembler, bitcode analyzer, and
bitcode optimizer. It also contains basic regression tests.</p>
<p>C-like languages use the <a class="reference external" href="https://clang.llvm.org/">Clang</a> front end. This
component compiles C, C++, Objective C, and Objective C++ code into LLVM bitcode
– and from there into object files, using LLVM.</p>
<p>Other components include:
the <a class="reference external" href="https://libcxx.llvm.org">libc++ C++ standard library</a>,
the <a class="reference external" href="https://lld.llvm.org">LLD linker</a>, and more.</p>
</div>
<div class="section" id="getting-the-source-code-and-building-llvm">
<h2><a class="toc-backref" href="#id5">Getting the Source Code and Building LLVM</a><a class="headerlink" href="#getting-the-source-code-and-building-llvm" title="Permalink to this headline">¶</a></h2>
<p>The LLVM Getting Started documentation may be out of date. The <a class="reference external" href="https://clang.llvm.org/get_started.html">Clang
Getting Started</a> page might have more
accurate information.</p>
<p>This is an example workflow and configuration to get and build the LLVM source:</p>
<ol class="arabic">
<li><p>Checkout LLVM (including related subprojects like Clang):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">https://github.com/llvm/llvm-project.git</span></code></p></li>
<li><p>Or, on windows, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">--config</span> <span class="pre">core.autocrlf=false</span>
<span class="pre">https://github.com/llvm/llvm-project.git</span></code></p></li>
<li><p>To save storage and speed-up the checkout time, you may want to do a
<a class="reference external" href="https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt">shallow clone</a>.
For example, to get the latest revision of the LLVM project, use
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span> <span class="pre">--depth</span> <span class="pre">1</span> <span class="pre">https://github.com/llvm/llvm-project.git</span></code></p></li>
</ul>
</li>
<li><p>Configure and build LLVM and Clang:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">llvm-project</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mkdir</span> <span class="pre">build</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">build</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">-G</span> <span class="pre"><generator></span> <span class="pre">[options]</span> <span class="pre">../llvm</span></code></p>
<p>Some common build system generators are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">Ninja</span></code> — for generating <a class="reference external" href="https://ninja-build.org">Ninja</a>
build files. Most llvm developers use Ninja.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Unix</span> <span class="pre">Makefiles</span></code> — for generating make-compatible parallel makefiles.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Visual</span> <span class="pre">Studio</span></code> — for generating Visual Studio projects and
solutions.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Xcode</span></code> — for generating Xcode projects.</p></li>
</ul>
<p>Some Common options:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_PROJECTS='...'</span></code> — semicolon-separated list of the LLVM
subprojects you’d like to additionally build. Can include any of: clang,
clang-tools-extra, libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld,
polly, or cross-project-tests.</p>
<p>For example, to build LLVM, Clang, libcxx, and libcxxabi, use
<code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"</span></code>.</p>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">-DCMAKE_INSTALL_PREFIX=directory</span></code> — Specify for <em>directory</em> the full
pathname of where you want the LLVM tools and libraries to be installed
(default <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code>).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-DCMAKE_BUILD_TYPE=type</span></code> — Valid options for <em>type</em> are Debug,
Release, RelWithDebInfo, and MinSizeRel. Default is Debug.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_ASSERTIONS=On</span></code> — Compile with assertion checks enabled
(default is Yes for Debug builds, No for all other build types).</p></li>
</ul>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span> <span class="pre">[--target</span> <span class="pre"><target>]</span></code> or the build system specified
above directly.</p>
<ul class="simple">
<li><p>The default target (i.e. <code class="docutils literal notranslate"><span class="pre">cmake</span> <span class="pre">--build</span> <span class="pre">.</span></code> or <code class="docutils literal notranslate"><span class="pre">make</span></code>) will build all of
LLVM.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">check-all</span></code> target (i.e. <code class="docutils literal notranslate"><span class="pre">ninja</span> <span class="pre">check-all</span></code>) will run the
regression tests to ensure everything is in working order.</p></li>
<li><p>CMake will generate build targets for each tool and library, and most
LLVM sub-projects generate their own <code class="docutils literal notranslate"><span class="pre">check-<project></span></code> target.</p></li>
<li><p>Running a serial build will be <strong>slow</strong>. To improve speed, try running a
parallel build. That’s done by default in Ninja; for <code class="docutils literal notranslate"><span class="pre">make</span></code>, use the
option <code class="docutils literal notranslate"><span class="pre">-j</span> <span class="pre">NN</span></code>, where <code class="docutils literal notranslate"><span class="pre">NN</span></code> is the number of parallel jobs, e.g. the
number of available CPUs.</p></li>
</ul>
</li>
<li><p>For more information see <a class="reference external" href="CMake.html">CMake</a></p></li>
<li><p>If you get an “internal compiler error (ICE)” or test failures, see
<a class="reference internal" href="#below">below</a>.</p></li>
</ul>
</li>
</ol>
<p>Consult the <a class="reference internal" href="#getting-started-with-llvm">Getting Started with LLVM</a> section for detailed information on
configuring and compiling LLVM. Go to <a class="reference internal" href="#directory-layout">Directory Layout</a> to learn about the
layout of the source code tree.</p>
</div>
<div class="section" id="requirements">
<h2><a class="toc-backref" href="#id6">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
<p>Before you begin to use the LLVM system, review the requirements given below.
This may save you some trouble by knowing ahead of time what hardware and
software you will need.</p>
<div class="section" id="hardware">
<h3><a class="toc-backref" href="#id7">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h3>
<p>LLVM is known to work on the following host platforms:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 35%" />
<col style="width: 40%" />
<col style="width: 25%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>OS</p></th>
<th class="head"><p>Arch</p></th>
<th class="head"><p>Compilers</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Linux</p></td>
<td><p>x86<sup>1</sup></p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>Linux</p></td>
<td><p>amd64</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>Linux</p></td>
<td><p>ARM</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>Linux</p></td>
<td><p>Mips</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>Linux</p></td>
<td><p>PowerPC</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>Linux</p></td>
<td><p>SystemZ</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>Solaris</p></td>
<td><p>V9 (Ultrasparc)</p></td>
<td><p>GCC</p></td>
</tr>
<tr class="row-odd"><td><p>FreeBSD</p></td>
<td><p>x86<sup>1</sup></p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>FreeBSD</p></td>
<td><p>amd64</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>NetBSD</p></td>
<td><p>x86<sup>1</sup></p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>NetBSD</p></td>
<td><p>amd64</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>OpenBSD</p></td>
<td><p>x86<sup>1</sup></p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-even"><td><p>OpenBSD</p></td>
<td><p>amd64</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>macOS<sup>2</sup></p></td>
<td><p>PowerPC</p></td>
<td><p>GCC</p></td>
</tr>
<tr class="row-even"><td><p>macOS</p></td>
<td><p>x86</p></td>
<td><p>GCC, Clang</p></td>
</tr>
<tr class="row-odd"><td><p>Cygwin/Win32</p></td>
<td><p>x86<sup>1, 3</sup></p></td>
<td><p>GCC</p></td>
</tr>
<tr class="row-even"><td><p>Windows</p></td>
<td><p>x86<sup>1</sup></p></td>
<td><p>Visual Studio</p></td>
</tr>
<tr class="row-odd"><td><p>Windows x64</p></td>
<td><p>x86-64</p></td>
<td><p>Visual Studio</p></td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ol class="arabic simple">
<li><p>Code generation supported for Pentium processors and up</p></li>
<li><p>Code generation supported for 32-bit ABI only</p></li>
<li><p>To use LLVM modules on Win32-based system, you may configure LLVM
with <code class="docutils literal notranslate"><span class="pre">-DBUILD_SHARED_LIBS=On</span></code>.</p></li>
</ol>
</div>
<p>Note that Debug builds require a lot of time and disk space. An LLVM-only build
will need about 1-3 GB of space. A full build of LLVM and Clang will need around
15-20 GB of disk space. The exact space requirements will vary by system. (It
is so large because of all the debugging information and the fact that the
libraries are statically linked into multiple tools).</p>
<p>If you are space-constrained, you can build only selected tools or only
selected targets. The Release build requires considerably less space.</p>
<p>The LLVM suite <em>may</em> compile on other platforms, but it is not guaranteed to do
so. If compilation is successful, the LLVM utilities should be able to
assemble, disassemble, analyze, and optimize LLVM bitcode. Code generation
should work as well, although the generated native code may not work on your
platform.</p>
</div>
<div class="section" id="software">
<h3><a class="toc-backref" href="#id8">Software</a><a class="headerlink" href="#software" title="Permalink to this headline">¶</a></h3>
<p>Compiling LLVM requires that you have several software packages installed. The
table below lists those required packages. The Package column is the usual name
for the software package that LLVM depends on. The Version column provides
“known to work” versions of the package. The Notes column describes how LLVM
uses the package and provides other details.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 52%" />
<col style="width: 11%" />
<col style="width: 37%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Package</p></th>
<th class="head"><p>Version</p></th>
<th class="head"><p>Notes</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference external" href="http://cmake.org/">CMake</a></p></td>
<td><p>>=3.13.4</p></td>
<td><p>Makefile/workspace generator</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="http://gcc.gnu.org/">GCC</a></p></td>
<td><p>>=5.1.0</p></td>
<td><p>C/C++ compiler<sup>1</sup></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="http://www.python.org/">python</a></p></td>
<td><p>>=3.6</p></td>
<td><p>Automated test suite<sup>2</sup></p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference external" href="http://zlib.net">zlib</a></p></td>
<td><p>>=1.2.3.4</p></td>
<td><p>Compression library<sup>3</sup></p></td>
</tr>
<tr class="row-even"><td><p><a class="reference external" href="http://savannah.gnu.org/projects/make">GNU Make</a></p></td>
<td><p>3.79, 3.79.1</p></td>
<td><p>Makefile/build processor<sup>4</sup></p></td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="admonition-title">Note</p>
<ol class="arabic simple">
<li><p>Only the C and C++ languages are needed so there’s no need to build the
other languages for LLVM’s purposes. See <cite>below</cite> for specific version
info.</p></li>
<li><p>Only needed if you want to run the automated test suite in the
<code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> directory.</p></li>
<li><p>Optional, adds compression / uncompression capabilities to selected LLVM
tools.</p></li>
<li><p>Optional, you can use any other build tool supported by CMake.</p></li>
</ol>
</div>
<p>Additionally, your compilation host is expected to have the usual plethora of
Unix utilities. Specifically:</p>
<ul class="simple">
<li><p><strong>ar</strong> — archive library builder</p></li>
<li><p><strong>bzip2</strong> — bzip2 command for distribution generation</p></li>
<li><p><strong>bunzip2</strong> — bunzip2 command for distribution checking</p></li>
<li><p><strong>chmod</strong> — change permissions on a file</p></li>
<li><p><strong>cat</strong> — output concatenation utility</p></li>
<li><p><strong>cp</strong> — copy files</p></li>
<li><p><strong>date</strong> — print the current date/time</p></li>
<li><p><strong>echo</strong> — print to standard output</p></li>
<li><p><strong>egrep</strong> — extended regular expression search utility</p></li>
<li><p><strong>find</strong> — find files/dirs in a file system</p></li>
<li><p><strong>grep</strong> — regular expression search utility</p></li>
<li><p><strong>gzip</strong> — gzip command for distribution generation</p></li>
<li><p><strong>gunzip</strong> — gunzip command for distribution checking</p></li>
<li><p><strong>install</strong> — install directories/files</p></li>
<li><p><strong>mkdir</strong> — create a directory</p></li>
<li><p><strong>mv</strong> — move (rename) files</p></li>
<li><p><strong>ranlib</strong> — symbol table builder for archive libraries</p></li>
<li><p><strong>rm</strong> — remove (delete) files and directories</p></li>
<li><p><strong>sed</strong> — stream editor for transforming output</p></li>
<li><p><strong>sh</strong> — Bourne shell for make build scripts</p></li>
<li><p><strong>tar</strong> — tape archive for distribution generation</p></li>
<li><p><strong>test</strong> — test things in file system</p></li>
<li><p><strong>unzip</strong> — unzip command for distribution checking</p></li>
<li><p><strong>zip</strong> — zip command for distribution generation</p></li>
</ul>
</div>
<div class="section" id="host-c-toolchain-both-compiler-and-standard-library">
<span id="check-here"></span><span id="below"></span><h3><a class="toc-backref" href="#id9">Host C++ Toolchain, both Compiler and Standard Library</a><a class="headerlink" href="#host-c-toolchain-both-compiler-and-standard-library" title="Permalink to this headline">¶</a></h3>
<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
bugs in the compiler. We also attempt to follow improvements and developments in
the C++ language and library reasonably closely. As such, we require a modern
host C++ toolchain, both compiler and standard library, in order to build LLVM.</p>
<p>LLVM is written using the subset of C++ documented in <a class="reference internal" href="CodingStandards.html"><span class="doc">coding
standards</span></a>. To enforce this language version, we check the most
popular host toolchains for specific minimum versions in our build systems:</p>
<ul class="simple">
<li><p>Clang 3.5</p></li>
<li><p>Apple Clang 6.0</p></li>
<li><p>GCC 5.1</p></li>
<li><p>Visual Studio 2017</p></li>
</ul>
<p>Anything older than these toolchains <em>may</em> work, but will require forcing the
build system with a special option and is not really a supported host platform.
Also note that older versions of these compilers have often crashed or
miscompiled LLVM.</p>
<p>For less widely used host toolchains such as ICC or xlC, be aware that a very
recent version may be required to support all of the C++ features used in LLVM.</p>
<p>We track certain versions of software that are <em>known</em> to fail when used as
part of the host toolchain. These even include linkers at times.</p>
<p><strong>GNU ld 2.16.X</strong>. Some 2.16.X versions of the ld linker will produce very long
warning messages complaining that some “<code class="docutils literal notranslate"><span class="pre">.gnu.linkonce.t.*</span></code>” symbol was
defined in a discarded section. You can safely ignore these messages as they are
erroneous and the linkage is correct. These messages disappear using ld 2.17.</p>
<p><strong>GNU binutils 2.17</strong>: Binutils 2.17 contains <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which causes huge link
times (minutes instead of seconds) when building LLVM. We recommend upgrading
to a newer version (2.17.50.0.4 or later).</p>
<p><strong>GNU Binutils 2.19.1 Gold</strong>: This version of Gold contained <a class="reference external" href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a> which causes
intermittent failures when building LLVM with position independent code. The
symptom is an error about cyclic dependencies. We recommend upgrading to a
newer version of Gold.</p>
<div class="section" id="getting-a-modern-host-c-toolchain">
<h4><a class="toc-backref" href="#id10">Getting a Modern Host C++ Toolchain</a><a class="headerlink" href="#getting-a-modern-host-c-toolchain" title="Permalink to this headline">¶</a></h4>
<p>This section mostly applies to Linux and older BSDs. On macOS, you should
have a sufficiently modern Xcode, or you will likely need to upgrade until you
do. Windows does not have a “system compiler”, so you must install either Visual
Studio 2017 or a recent version of mingw64. FreeBSD 10.0 and newer have a modern
Clang as the system compiler.</p>
<p>However, some Linux distributions and some other or older BSDs sometimes have
extremely old versions of GCC. These steps attempt to help you upgrade you
compiler even on such a system. However, if at all possible, we encourage you
to use a recent version of a distribution with a modern system compiler that
meets these requirements. Note that it is tempting to install a prior
version of Clang and libc++ to be the host compiler, however libc++ was not
well tested or set up to build on Linux until relatively recently. As
a consequence, this guide suggests just using libstdc++ and a modern GCC as the
initial host in a bootstrap, and then using Clang (and potentially libc++).</p>
<p>The first step is to get a recent GCC toolchain installed. The most common
distribution on which users have struggled with the version requirements is
Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
the <a class="reference external" href="https://launchpad.net/~ubuntu-toolchain-r/+archive/test">toolchain testing PPA</a> and use it to install a modern GCC. There is
a really nice discussions of this on the <a class="reference external" href="https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149">ask ubuntu stack exchange</a> and a
<a class="reference external" href="https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91">github gist</a> with updated commands. However, not all users can use PPAs and
there are many other distributions, so it may be necessary (or just useful, if
you’re here you <em>are</em> doing compiler development after all) to build and install
GCC from source. It is also quite easy to do these days.</p>
<p>Easy steps for installing GCC 5.1.0:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nv">gcc_version</span><span class="o">=</span><span class="m">5</span>.1.0
<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2
<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gcc/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2.sig
<span class="gp">%</span> wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
<span class="gp">%</span> <span class="nv">signature_invalid</span><span class="o">=</span><span class="sb">`</span>gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2.sig<span class="sb">`</span>
<span class="gp">%</span> <span class="k">if</span> <span class="o">[</span> <span class="nv">$signature_invalid</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span> <span class="nb">echo</span> <span class="s2">"Invalid signature"</span> <span class="p">;</span> <span class="nb">exit</span> <span class="m">1</span> <span class="p">;</span> <span class="k">fi</span>
<span class="gp">%</span> tar -xvjf gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>.tar.bz2
<span class="gp">%</span> <span class="nb">cd</span> gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>
<span class="gp">%</span> ./contrib/download_prerequisites
<span class="gp">%</span> <span class="nb">cd</span> ..
<span class="gp">%</span> mkdir gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>-build
<span class="gp">%</span> <span class="nb">cd</span> gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>-build
<span class="gp">%</span> <span class="nv">$PWD</span>/../gcc-<span class="si">${</span><span class="nv">gcc_version</span><span class="si">}</span>/configure --prefix<span class="o">=</span><span class="nv">$HOME</span>/toolchains --enable-languages<span class="o">=</span>c,c++
<span class="gp">%</span> make -j<span class="k">$(</span>nproc<span class="k">)</span>
<span class="gp">%</span> make install
</pre></div>
</div>
<p>For more details, check out the excellent <a class="reference external" href="https://gcc.gnu.org/wiki/InstallingGCC">GCC wiki entry</a>, where I got most
of this information from.</p>
<p>Once you have a GCC toolchain, configure your build of LLVM to use the new
toolchain for your host compiler and C++ standard library. Because the new
version of libstdc++ is not on the system library search path, you need to pass
extra linker flags so that it can be found at link time (<code class="docutils literal notranslate"><span class="pre">-L</span></code>) and at runtime
(<code class="docutils literal notranslate"><span class="pre">-rpath</span></code>). If you are using CMake, this invocation should produce working
binaries:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> mkdir build
<span class="gp">%</span> <span class="nb">cd</span> build
<span class="gp">%</span> <span class="nv">CC</span><span class="o">=</span><span class="nv">$HOME</span>/toolchains/bin/gcc <span class="nv">CXX</span><span class="o">=</span><span class="nv">$HOME</span>/toolchains/bin/g++ <span class="se">\</span>
cmake .. -DCMAKE_CXX_LINK_FLAGS<span class="o">=</span><span class="s2">"-Wl,-rpath,</span><span class="nv">$HOME</span><span class="s2">/toolchains/lib64 -L</span><span class="nv">$HOME</span><span class="s2">/toolchains/lib64"</span>
</pre></div>
</div>
<p>If you fail to set rpath, most LLVM binaries will fail on startup with a message
from the loader similar to <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6:</span> <span class="pre">version</span> <span class="pre">`GLIBCXX_3.4.20'</span> <span class="pre">not</span>
<span class="pre">found</span></code>. This means you need to tweak the -rpath linker flag.</p>
<p>This method will add an absolute path to the rpath of all executables. That’s
fine for local development. If you want to distribute the binaries you build
so that they can run on older systems, copy <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6</span></code> into the
<code class="docutils literal notranslate"><span class="pre">lib/</span></code> directory. All of LLVM’s shipping binaries have an rpath pointing at
<code class="docutils literal notranslate"><span class="pre">$ORIGIN/../lib</span></code>, so they will find <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6</span></code> there. Non-distributed
binaries don’t have an rpath set and won’t find <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6</span></code>. Pass
<code class="docutils literal notranslate"><span class="pre">-DLLVM_LOCAL_RPATH="$HOME/toolchains/lib64"</span></code> to cmake to add an absolute
path to <code class="docutils literal notranslate"><span class="pre">libstdc++.so.6</span></code> as above. Since these binaries are not distributed,
having an absolute local path is fine for them.</p>
<p>When you build Clang, you will need to give <em>it</em> access to modern C++
standard library in order to use it as your new host in part of a bootstrap.
There are two easy ways to do this, either build (and install) libc++ along
with Clang and then use it with the <code class="docutils literal notranslate"><span class="pre">-stdlib=libc++</span></code> compile and link flag,
or install Clang into the same prefix (<code class="docutils literal notranslate"><span class="pre">$HOME/toolchains</span></code> above) as GCC.
Clang will look within its own prefix for libstdc++ and use it if found. You
can also add an explicit prefix for Clang to look in for a GCC toolchain with
the <code class="docutils literal notranslate"><span class="pre">--gcc-toolchain=/opt/my/gcc/prefix</span></code> flag, passing it to both compile and
link commands when using your just-built-Clang to bootstrap.</p>
</div>
</div>
</div>
<div class="section" id="getting-started-with-llvm">
<span id="id1"></span><h2><a class="toc-backref" href="#id11">Getting Started with LLVM</a><a class="headerlink" href="#getting-started-with-llvm" title="Permalink to this headline">¶</a></h2>
<p>The remainder of this guide is meant to get you up and running with LLVM and to
give you some basic information about the LLVM environment.</p>
<p>The later sections of this guide describe the <a class="reference internal" href="#general-layout">general layout</a> of the LLVM
source tree, a <a class="reference internal" href="#simple-example">simple example</a> using the LLVM tool chain, and <a class="reference internal" href="#links">links</a> to find
more information about LLVM or to get help via e-mail.</p>
<div class="section" id="terminology-and-notation">
<h3><a class="toc-backref" href="#id12">Terminology and Notation</a><a class="headerlink" href="#terminology-and-notation" title="Permalink to this headline">¶</a></h3>
<p>Throughout this manual, the following names are used to denote paths specific to
the local system and working environment. <em>These are not environment variables
you need to set but just strings used in the rest of this document below</em>. In
any of the examples below, simply replace each of these names with the
appropriate pathname on your local system. All these paths are absolute:</p>
<p><code class="docutils literal notranslate"><span class="pre">SRC_ROOT</span></code></p>
<blockquote>
<div><p>This is the top level directory of the LLVM source tree.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">OBJ_ROOT</span></code></p>
<blockquote>
<div><p>This is the top level directory of the LLVM object tree (i.e. the tree where
object files and compiled programs will be placed. It can be the same as
SRC_ROOT).</p>
</div></blockquote>
</div>
<div class="section" id="unpacking-the-llvm-archives">
<h3><a class="toc-backref" href="#id13">Unpacking the LLVM Archives</a><a class="headerlink" href="#unpacking-the-llvm-archives" title="Permalink to this headline">¶</a></h3>
<p>If you have the LLVM distribution, you will need to unpack it before you can
begin to compile it. LLVM is distributed as a number of different
subprojects. Each one has its own download which is a TAR archive that is
compressed with the gzip program.</p>
<p>The files are as follows, with <em>x.y</em> marking the version number:</p>
<p><code class="docutils literal notranslate"><span class="pre">llvm-x.y.tar.gz</span></code></p>
<blockquote>
<div><p>Source release for the LLVM libraries and tools.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">cfe-x.y.tar.gz</span></code></p>
<blockquote>
<div><p>Source release for the Clang frontend.</p>
</div></blockquote>
</div>
<div class="section" id="checkout-llvm-from-git">
<span id="checkout"></span><h3><a class="toc-backref" href="#id14">Checkout LLVM from Git</a><a class="headerlink" href="#checkout-llvm-from-git" title="Permalink to this headline">¶</a></h3>
<p>You can also checkout the source code for LLVM from Git.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Passing <code class="docutils literal notranslate"><span class="pre">--config</span> <span class="pre">core.autocrlf=false</span></code> should not be required in
the future after we adjust the .gitattribute settings correctly, but
is required for Windows users at the time of this writing.</p>
</div>
<p>Simply run:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clone https://github.com/llvm/llvm-project.git
</pre></div>
</div>
<p>or on Windows,</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clone --config core.autocrlf<span class="o">=</span><span class="nb">false</span> https://github.com/llvm/llvm-project.git
</pre></div>
</div>
<p>This will create an ‘<code class="docutils literal notranslate"><span class="pre">llvm-project</span></code>’ directory in the current directory and
fully populate it with all of the source code, test directories, and local
copies of documentation files for LLVM and all the related subprojects. Note
that unlike the tarballs, which contain each subproject in a separate file, the
git repository contains all of the projects together.</p>
<p>If you want to get a specific release (as opposed to the most recent revision),
you can check out a tag after cloning the repository. E.g., <cite>git checkout
llvmorg-6.0.1</cite> inside the <code class="docutils literal notranslate"><span class="pre">llvm-project</span></code> directory created by the above
command. Use <cite>git tag -l</cite> to list all of them.</p>
<div class="section" id="sending-patches">
<h4><a class="toc-backref" href="#id15">Sending patches</a><a class="headerlink" href="#sending-patches" title="Permalink to this headline">¶</a></h4>
<p>Please read <a class="reference external" href="DeveloperPolicy.html#one-off-patches">Developer Policy</a>, too.</p>
<p>We don’t currently accept github pull requests, so you’ll need to send patches
either via emailing to llvm-commits, or, preferably, via <a class="reference internal" href="Phabricator.html#phabricator-reviews"><span class="std std-ref">Phabricator</span></a>.</p>
<p>You’ll generally want to make sure your branch has a single commit,
corresponding to the review you wish to send, up-to-date with the upstream
<code class="docutils literal notranslate"><span class="pre">origin/main</span></code> branch, and doesn’t contain merges. Once you have that, you
can start <a class="reference external" href="Phabricator.html">a Phabricator review</a> (or use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">show</span></code> or
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">format-patch</span></code> to output the diff, and attach it to an email message).</p>
<p>However, using the “Arcanist” tool is often easier. After <a class="reference external" href="https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/">installing
arcanist</a>, you can upload the latest commit using:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> arc diff HEAD~1
</pre></div>
</div>
<p>Additionally, before sending a patch for review, please also try to ensure it’s
formatted properly. We use <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> for this, which has git integration
through the <code class="docutils literal notranslate"><span class="pre">git-clang-format</span></code> script. On some systems, it may already be
installed (or be installable via your package manager). If so, you can simply
run it – the following command will format only the code changed in the most
recent commit:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git clang-format HEAD~1
</pre></div>
</div>
<p>Note that this modifies the files, but doesn’t commit them – you’ll likely want
to run</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> git commit --amend -a
</pre></div>
</div>
<p>in order to update the last commit with all pending changes.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you don’t already have <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clang-format</span></code> installed
on your system, the <code class="docutils literal notranslate"><span class="pre">clang-format</span></code> binary will be built alongside clang, and
the git integration can be run from
<code class="docutils literal notranslate"><span class="pre">clang/tools/clang-format/git-clang-format</span></code>.</p>
</div>
</div>
<div class="section" id="for-developers-to-commit-changes-from-git">
<span id="commit-from-git"></span><h4><a class="toc-backref" href="#id16">For developers to commit changes from Git</a><a class="headerlink" href="#for-developers-to-commit-changes-from-git" title="Permalink to this headline">¶</a></h4>
<p>Once a patch is reviewed, you should rebase it, re-test locally, and commit the
changes to LLVM’s main branch. This is done using <cite>git push</cite> if you have the
required access rights. See <a class="reference external" href="Phabricator.html#committing-a-change">committing a change</a> for Phabricator based commits or
<a class="reference external" href="DeveloperPolicy.html#obtaining-commit-access">obtaining commit access</a>
for commit access.</p>
<p>Here is an example workflow using git. This workflow assumes you have an
accepted commit on the branch named <cite>branch-with-change</cite>.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span> Go to the branch with your accepted commit.
<span class="gp">%</span> git checkout branch-with-change
<span class="gp">#</span> Rebase your change onto the latest commits on Github.
<span class="gp">%</span> git pull --rebase origin main
<span class="gp">#</span> Rerun the appropriate tests <span class="k">if</span> needed.
<span class="gp">%</span> ninja check-<span class="nv">$whatever</span>
<span class="gp">#</span> Check that the list of commits about to be pushed is correct.
<span class="gp">%</span> git log origin/main...HEAD --oneline
<span class="gp">#</span> Push to Github.
<span class="gp">%</span> git push origin HEAD:main
</pre></div>
</div>
<p>LLVM currently has a linear-history policy, which means that merge commits are
not allowed. The <cite>llvm-project</cite> repo on github is configured to reject pushes
that include merges, so the <cite>git rebase</cite> step above is required.</p>
<p>Please ask for help if you’re having trouble with your particular git workflow.</p>
</div>
<div class="section" id="git-pre-push-hook">
<span id="id2"></span><h4><a class="toc-backref" href="#id17">Git pre-push hook</a><a class="headerlink" href="#git-pre-push-hook" title="Permalink to this headline">¶</a></h4>
<p>We include an optional pre-push hook that run some sanity checks on the revisions
you are about to push and ask confirmation if you push multiple commits at once.
You can set it up (on Unix systems) by running from the repository root:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> ln -sf ../../llvm/utils/git/pre-push.py .git/hooks/pre-push
</pre></div>
</div>
</div>
<div class="section" id="bisecting-commits">
<h4><a class="toc-backref" href="#id18">Bisecting commits</a><a class="headerlink" href="#bisecting-commits" title="Permalink to this headline">¶</a></h4>
<p>See <a class="reference external" href="GitBisecting.html">Bisecting LLVM code</a> for how to use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">bisect</span></code>
on LLVM.</p>
</div>
<div class="section" id="reverting-a-change">
<h4><a class="toc-backref" href="#id19">Reverting a change</a><a class="headerlink" href="#reverting-a-change" title="Permalink to this headline">¶</a></h4>
<p>When reverting changes using git, the default message will say “This reverts
commit XYZ”. Leave this at the end of the commit message, but add some details
before it as to why the commit is being reverted. A brief explanation and/or
links to bots that demonstrate the problem are sufficient.</p>
</div>
</div>
<div class="section" id="local-llvm-configuration">
<h3><a class="toc-backref" href="#id20">Local LLVM Configuration</a><a class="headerlink" href="#local-llvm-configuration" title="Permalink to this headline">¶</a></h3>
<p>Once checked out repository, the LLVM suite source code must be configured
before being built. This process uses CMake. Unlinke the normal <code class="docutils literal notranslate"><span class="pre">configure</span></code>
script, CMake generates the build files in whatever format you request as well
as various <code class="docutils literal notranslate"><span class="pre">*.inc</span></code> files, and <code class="docutils literal notranslate"><span class="pre">llvm/include/Config/config.h</span></code>.</p>
<p>Variables are passed to <code class="docutils literal notranslate"><span class="pre">cmake</span></code> on the command line using the format
<code class="docutils literal notranslate"><span class="pre">-D<variable</span> <span class="pre">name>=<value></span></code>. The following variables are some common options
used by people developing LLVM.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 32%" />
<col style="width: 68%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Variable</p></th>
<th class="head"><p>Purpose</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>CMAKE_C_COMPILER</p></td>
<td><p>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> which C compiler to use. By
default, this will be /usr/bin/cc.</p></td>
</tr>
<tr class="row-odd"><td><p>CMAKE_CXX_COMPILER</p></td>
<td><p>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> which C++ compiler to use. By
default, this will be /usr/bin/c++.</p></td>
</tr>
<tr class="row-even"><td><p>CMAKE_BUILD_TYPE</p></td>
<td><p>Tells <code class="docutils literal notranslate"><span class="pre">cmake</span></code> what type of build you are trying
to generate files for. Valid options are Debug,
Release, RelWithDebInfo, and MinSizeRel. Default
is Debug.</p></td>
</tr>
<tr class="row-odd"><td><p>CMAKE_INSTALL_PREFIX</p></td>
<td><p>Specifies the install directory to target when
running the install action of the build files.</p></td>
</tr>
<tr class="row-even"><td><p>PYTHON_EXECUTABLE</p></td>
<td><p>Forces CMake to use a specific Python version by
passing a path to a Python interpreter. By default
the Python version of the interpreter in your PATH
is used.</p></td>
</tr>
<tr class="row-odd"><td><p>LLVM_TARGETS_TO_BUILD</p></td>
<td><p>A semicolon delimited list controlling which
targets will be built and linked into llvm.
The default list is defined as
<code class="docutils literal notranslate"><span class="pre">LLVM_ALL_TARGETS</span></code>, and can be set to include
out-of-tree targets. The default value includes:
<code class="docutils literal notranslate"><span class="pre">AArch64,</span> <span class="pre">AMDGPU,</span> <span class="pre">ARM,</span> <span class="pre">AVR,</span> <span class="pre">BPF,</span> <span class="pre">Hexagon,</span> <span class="pre">Lanai,</span>
<span class="pre">Mips,</span> <span class="pre">MSP430,</span> <span class="pre">NVPTX,</span> <span class="pre">PowerPC,</span> <span class="pre">RISCV,</span> <span class="pre">Sparc,</span>
<span class="pre">SystemZ,</span> <span class="pre">WebAssembly,</span> <span class="pre">X86,</span> <span class="pre">XCore</span></code>.</p></td>
</tr>
<tr class="row-even"><td><p>LLVM_ENABLE_DOXYGEN</p></td>
<td><p>Build doxygen-based documentation from the source
code This is disabled by default because it is
slow and generates a lot of output.</p></td>
</tr>
<tr class="row-odd"><td><p>LLVM_ENABLE_PROJECTS</p></td>
<td><p>A semicolon-delimited list selecting which of the
other LLVM subprojects to additionally build. (Only
effective when using a side-by-side project layout
e.g. via git). The default list is empty. Can
include: clang, libcxx, libcxxabi, libunwind, lldb,
compiler-rt, lld, polly, or debuginfo-tests.</p></td>
</tr>
<tr class="row-even"><td><p>LLVM_ENABLE_SPHINX</p></td>
<td><p>Build sphinx-based documentation from the source
code. This is disabled by default because it is
slow and generates a lot of output. Sphinx version
1.5 or later recommended.</p></td>
</tr>
<tr class="row-odd"><td><p>LLVM_BUILD_LLVM_DYLIB</p></td>
<td><p>Generate libLLVM.so. This library contains a
default set of LLVM components that can be
overridden with <code class="docutils literal notranslate"><span class="pre">LLVM_DYLIB_COMPONENTS</span></code>. The
default contains most of LLVM and is defined in
<code class="docutils literal notranslate"><span class="pre">tools/llvm-shlib/CMakelists.txt</span></code>. This option is
not available on Windows.</p></td>
</tr>
<tr class="row-even"><td><p>LLVM_OPTIMIZED_TABLEGEN</p></td>
<td><p>Builds a release tablegen that gets used during
the LLVM build. This can dramatically speed up
debug builds.</p></td>
</tr>
</tbody>
</table>
<p>To configure LLVM, follow these steps:</p>
<ol class="arabic">
<li><p>Change directory into the object root directory:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> OBJ_ROOT
</pre></div>
</div>
</li>
<li><p>Run the <code class="docutils literal notranslate"><span class="pre">cmake</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> -DCMAKE_INSTALL_PREFIX<span class="o">=</span>/install/path
<span class="go"> [other options] SRC_ROOT</span>
</pre></div>
</div>
</li>
</ol>
</div>
<div class="section" id="compiling-the-llvm-suite-source-code">
<h3><a class="toc-backref" href="#id21">Compiling the LLVM Suite Source Code</a><a class="headerlink" href="#compiling-the-llvm-suite-source-code" title="Permalink to this headline">¶</a></h3>
<p>Unlike with autotools, with CMake your build type is defined at configuration.
If you want to change your build type, you can re-run cmake with the following
invocation:</p>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> -DCMAKE_BUILD_TYPE<span class="o">=</span><span class="nb">type</span> SRC_ROOT
</pre></div>
</div>
</div></blockquote>
<p>Between runs, CMake preserves the values set for all options. CMake has the
following build types defined:</p>
<p>Debug</p>
<blockquote>
<div><p>These builds are the default. The build system will compile the tools and
libraries unoptimized, with debugging information, and asserts enabled.</p>
</div></blockquote>
<p>Release</p>
<blockquote>
<div><p>For these builds, the build system will compile the tools and libraries
with optimizations enabled and not generate debug info. CMakes default
optimization level is -O3. This can be configured by setting the
<code class="docutils literal notranslate"><span class="pre">CMAKE_CXX_FLAGS_RELEASE</span></code> variable on the CMake command line.</p>
</div></blockquote>
<p>RelWithDebInfo</p>
<blockquote>
<div><p>These builds are useful when debugging. They generate optimized binaries with
debug information. CMakes default optimization level is -O2. This can be
configured by setting the <code class="docutils literal notranslate"><span class="pre">CMAKE_CXX_FLAGS_RELWITHDEBINFO</span></code> variable on the
CMake command line.</p>
</div></blockquote>
<p>Once you have LLVM configured, you can build it by entering the <em>OBJ_ROOT</em>
directory and issuing the following command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> make
</pre></div>
</div>
<p>If the build fails, please <a class="reference internal" href="#check-here">check here</a> to see if you are using a version of
GCC that is known not to compile LLVM.</p>
<p>If you have multiple processors in your machine, you may wish to use some of the
parallel build options provided by GNU Make. For example, you could use the
command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> make -j2
</pre></div>
</div>
<p>There are several special targets which are useful when working with the LLVM
source code:</p>
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code></p>
<blockquote>
<div><p>Removes all files generated by the build. This includes object files,
generated C/C++ files, libraries, and executables.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code></p>
<blockquote>
<div><p>Installs LLVM header files, libraries, tools, and documentation in a hierarchy
under <code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code>, specified with <code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code>, which
defaults to <code class="docutils literal notranslate"><span class="pre">/usr/local</span></code>.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">docs-llvm-html</span></code></p>
<blockquote>
<div><p>If configured with <code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_SPHINX=On</span></code>, this will generate a directory
at <code class="docutils literal notranslate"><span class="pre">OBJ_ROOT/docs/html</span></code> which contains the HTML formatted documentation.</p>
</div></blockquote>
</div>
<div class="section" id="cross-compiling-llvm">
<h3><a class="toc-backref" href="#id22">Cross-Compiling LLVM</a><a class="headerlink" href="#cross-compiling-llvm" title="Permalink to this headline">¶</a></h3>
<p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
executables and libraries to be hosted on a platform different from the platform
where they are built (a Canadian Cross build). To generate build files for
cross-compiling CMake provides a variable <code class="docutils literal notranslate"><span class="pre">CMAKE_TOOLCHAIN_FILE</span></code> which can
define compiler flags and variables used during the CMake test operations.</p>
<p>The result of such a build is executables that are not runnable on the build
host but can be executed on the target. As an example the following CMake
invocation can generate build files targeting iOS. This will work on macOS
with the latest Xcode:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Ninja"</span> -DCMAKE_OSX_ARCHITECTURES<span class="o">=</span><span class="s2">"armv7;armv7s;arm64"</span>
<span class="go"> -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake</span>
<span class="go"> -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off</span>
<span class="go"> -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]</span>
<span class="go"> <PATH_TO_LLVM></span>
</pre></div>
</div>
<p>Note: There are some additional flags that need to be passed when building for
iOS due to limitations in the iOS SDK.</p>
<p>Check <a class="reference internal" href="HowToCrossCompileLLVM.html"><span class="doc">How To Cross-Compile Clang/LLVM using Clang/LLVM</span></a> and <a class="reference external" href="https://clang.llvm.org/docs/CrossCompilation.html">Clang docs on how to cross-compile in general</a> for more information
about cross-compiling.</p>
</div>
<div class="section" id="the-location-of-llvm-object-files">
<h3><a class="toc-backref" href="#id23">The Location of LLVM Object Files</a><a class="headerlink" href="#the-location-of-llvm-object-files" title="Permalink to this headline">¶</a></h3>
<p>The LLVM build system is capable of sharing a single LLVM source tree among
several LLVM builds. Hence, it is possible to build LLVM for several different
platforms or configurations using the same source tree.</p>
<ul>
<li><p>Change directory to where the LLVM object files should live:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> OBJ_ROOT
</pre></div>
</div>
</li>
<li><p>Run <code class="docutils literal notranslate"><span class="pre">cmake</span></code>:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> cmake -G <span class="s2">"Unix Makefiles"</span> SRC_ROOT
</pre></div>
</div>
</li>
</ul>
<p>The LLVM build will create a structure underneath <em>OBJ_ROOT</em> that matches the
LLVM source tree. At each level where source files are present in the source
tree there will be a corresponding <code class="docutils literal notranslate"><span class="pre">CMakeFiles</span></code> directory in the <em>OBJ_ROOT</em>.
Underneath that directory there is another directory with a name ending in
<code class="docutils literal notranslate"><span class="pre">.dir</span></code> under which you’ll find object files for each source.</p>
<p>For example:</p>
<blockquote>
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> <span class="nb">cd</span> llvm_build_dir
<span class="gp">%</span> find lib/Support/ -name APFloat*
<span class="go">lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o</span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="optional-configuration-items">
<h3><a class="toc-backref" href="#id24">Optional Configuration Items</a><a class="headerlink" href="#optional-configuration-items" title="Permalink to this headline">¶</a></h3>
<p>If you’re running on a Linux system that supports the <a class="reference external" href="http://en.wikipedia.org/wiki/binfmt_misc">binfmt_misc</a>
module, and you have root access on the system, you can set your system up to
execute LLVM bitcode files directly. To do this, use commands like this (the
first command may not be required if you are already using the module):</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
<span class="gp">%</span> <span class="nb">echo</span> <span class="s1">':llvm:M::BC::/path/to/lli:'</span> > /proc/sys/fs/binfmt_misc/register
<span class="gp">%</span> chmod u+x hello.bc <span class="o">(</span><span class="k">if</span> needed<span class="o">)</span>
<span class="gp">%</span> ./hello.bc
</pre></div>
</div>
<p>This allows you to execute LLVM bitcode files directly. On Debian, you can also
use this command instead of the ‘echo’ command above:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> sudo update-binfmts --install llvm /path/to/lli --magic <span class="s1">'BC'</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="directory-layout">
<span id="general-layout"></span><span id="program-layout"></span><h2><a class="toc-backref" href="#id25">Directory Layout</a><a class="headerlink" href="#directory-layout" title="Permalink to this headline">¶</a></h2>
<p>One useful source of information about the LLVM source base is the LLVM <a class="reference external" href="http://www.doxygen.org/">doxygen</a> documentation available at
<a class="reference external" href="https://llvm.org/doxygen/">https://llvm.org/doxygen/</a>. The following is a brief introduction to code
layout:</p>
<div class="section" id="llvm-cmake">
<h3><a class="toc-backref" href="#id26"><code class="docutils literal notranslate"><span class="pre">llvm/cmake</span></code></a><a class="headerlink" href="#llvm-cmake" title="Permalink to this headline">¶</a></h3>
<p>Generates system build files.</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">llvm/cmake/modules</span></code></dt><dd><p>Build configuration for llvm user defined options. Checks compiler version and
linker flags.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">llvm/cmake/platforms</span></code></dt><dd><p>Toolchain configuration for Android NDK, iOS systems and non-Windows hosts to
target MSVC.</p>
</dd>
</dl>
</div>
<div class="section" id="llvm-examples">
<h3><a class="toc-backref" href="#id27"><code class="docutils literal notranslate"><span class="pre">llvm/examples</span></code></a><a class="headerlink" href="#llvm-examples" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><p>Some simple examples showing how to use LLVM as a compiler for a custom
language - including lowering, optimization, and code generation.</p></li>
<li><p>Kaleidoscope Tutorial: Kaleidoscope language tutorial run through the
implementation of a nice little compiler for a non-trivial language
including a hand-written lexer, parser, AST, as well as code generation
support using LLVM- both static (ahead of time) and various approaches to
Just In Time (JIT) compilation.
<a class="reference external" href="https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html">Kaleidoscope Tutorial for complete beginner</a>.</p></li>
<li><p>BuildingAJIT: Examples of the <a class="reference external" href="https://llvm.org/docs/tutorial/BuildingAJIT1.html">BuildingAJIT tutorial</a> that shows how LLVM’s
ORC JIT APIs interact with other parts of LLVM. It also, teaches how to
recombine them to build a custom JIT that is suited to your use-case.</p></li>
</ul>
</div>
<div class="section" id="llvm-include">
<h3><a class="toc-backref" href="#id28"><code class="docutils literal notranslate"><span class="pre">llvm/include</span></code></a><a class="headerlink" href="#llvm-include" title="Permalink to this headline">¶</a></h3>
<p>Public header files exported from the LLVM library. The three main subdirectories:</p>
<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm</span></code></p>
<blockquote>
<div><p>All LLVM-specific header files, and subdirectories for different portions of
LLVM: <code class="docutils literal notranslate"><span class="pre">Analysis</span></code>, <code class="docutils literal notranslate"><span class="pre">CodeGen</span></code>, <code class="docutils literal notranslate"><span class="pre">Target</span></code>, <code class="docutils literal notranslate"><span class="pre">Transforms</span></code>, etc…</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Support</span></code></p>
<blockquote>
<div><p>Generic support libraries provided with LLVM but not necessarily specific to
LLVM. For example, some C++ STL utilities and a Command Line option processing
library store header files here.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Config</span></code></p>
<blockquote>
<div><p>Header files configured by <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. They wrap “standard” UNIX and
C header files. Source code can include these header files which
automatically take care of the conditional #includes that <code class="docutils literal notranslate"><span class="pre">cmake</span></code>
generates.</p>
</div></blockquote>
</div>
<div class="section" id="llvm-lib">
<h3><a class="toc-backref" href="#id29"><code class="docutils literal notranslate"><span class="pre">llvm/lib</span></code></a><a class="headerlink" href="#llvm-lib" title="Permalink to this headline">¶</a></h3>
<p>Most source files are here. By putting code in libraries, LLVM makes it easy to
share code among the <a class="reference internal" href="#tools">tools</a>.</p>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/</span></code></p>
<blockquote>
<div><p>Core LLVM source files that implement core classes like Instruction and
BasicBlock.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/</span></code></p>
<blockquote>
<div><p>Source code for the LLVM assembly language parser library.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/</span></code></p>
<blockquote>
<div><p>Code for reading and writing bitcode.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Analysis/</span></code></p>
<blockquote>
<div><p>A variety of program analyses, such as Call Graphs, Induction Variables,
Natural Loop Identification, etc.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Transforms/</span></code></p>
<blockquote>
<div><p>IR-to-IR program transformations, such as Aggressive Dead Code Elimination,
Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion,
Dead Global Elimination, and many others.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/</span></code></p>
<blockquote>
<div><p>Files describing target architectures for code generation. For example,
<code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/X86</span></code> holds the X86 machine description.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/CodeGen/</span></code></p>
<blockquote>
<div><p>The major parts of the code generator: Instruction Selector, Instruction
Scheduling, and Register Allocation.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/MC/</span></code></p>
<blockquote>
<div><p>The libraries represent and process code at machine code level. Handles
assembly and object-file emission.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/ExecutionEngine/</span></code></p>
<blockquote>
<div><p>Libraries for directly executing bitcode at runtime in interpreted and
JIT-compiled scenarios.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm/lib/Support/</span></code></p>
<blockquote>
<div><p>Source code that corresponding to the header files in <code class="docutils literal notranslate"><span class="pre">llvm/include/ADT/</span></code>
and <code class="docutils literal notranslate"><span class="pre">llvm/include/Support/</span></code>.</p>
</div></blockquote>
</div>
<div class="section" id="llvm-bindings">
<h3><a class="toc-backref" href="#id30"><code class="docutils literal notranslate"><span class="pre">llvm/bindings</span></code></a><a class="headerlink" href="#llvm-bindings" title="Permalink to this headline">¶</a></h3>
<p>Contains bindings for the LLVM compiler infrastructure to allow
programs written in languages other than C or C++ to take advantage of the LLVM
infrastructure.
LLVM project provides language bindings for Go, OCaml and Python.</p>
</div>
<div class="section" id="llvm-projects">
<h3><a class="toc-backref" href="#id31"><code class="docutils literal notranslate"><span class="pre">llvm/projects</span></code></a><a class="headerlink" href="#llvm-projects" title="Permalink to this headline">¶</a></h3>
<p>Projects not strictly part of LLVM but shipped with LLVM. This is also the
directory for creating your own LLVM-based projects which leverage the LLVM
build system.</p>
</div>
<div class="section" id="llvm-test">
<h3><a class="toc-backref" href="#id32"><code class="docutils literal notranslate"><span class="pre">llvm/test</span></code></a><a class="headerlink" href="#llvm-test" title="Permalink to this headline">¶</a></h3>
<p>Feature and regression tests and other sanity checks on LLVM infrastructure. These
are intended to run quickly and cover a lot of territory without being exhaustive.</p>
</div>
<div class="section" id="test-suite">
<h3><a class="toc-backref" href="#id33"><code class="docutils literal notranslate"><span class="pre">test-suite</span></code></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
<p>A comprehensive correctness, performance, and benchmarking test suite
for LLVM. This comes in a <code class="docutils literal notranslate"><span class="pre">separate</span> <span class="pre">git</span> <span class="pre">repository</span>
<span class="pre"><https://github.com/llvm/llvm-test-suite></span></code>, because it contains a
large amount of third-party code under a variety of licenses. For
details see the <a class="reference internal" href="TestingGuide.html"><span class="doc">Testing Guide</span></a> document.</p>
</div>
<div class="section" id="llvm-tools">
<span id="tools"></span><h3><a class="toc-backref" href="#id34"><code class="docutils literal notranslate"><span class="pre">llvm/tools</span></code></a><a class="headerlink" href="#llvm-tools" title="Permalink to this headline">¶</a></h3>
<p>Executables built out of the libraries
above, which form the main part of the user interface. You can always get help
for a tool by typing <code class="docutils literal notranslate"><span class="pre">tool_name</span> <span class="pre">-help</span></code>. The following is a brief introduction
to the most important tools. More detailed information is in
the <a class="reference external" href="CommandGuide/index.html">Command Guide</a>.</p>
<p><code class="docutils literal notranslate"><span class="pre">bugpoint</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> is used to debug optimization passes or code generation backends
by narrowing down the given test case to the minimum number of passes and/or
instructions that still cause a problem, whether it is a crash or
miscompilation. See <a class="reference external" href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information on using
<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code>.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm-ar</span></code></p>
<blockquote>
<div><p>The archiver produces an archive containing the given LLVM bitcode files,
optionally with an index for faster lookup.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm-as</span></code></p>
<blockquote>
<div><p>The assembler transforms the human readable LLVM assembly to LLVM bitcode.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm-dis</span></code></p>
<blockquote>
<div><p>The disassembler transforms the LLVM bitcode to human readable LLVM assembly.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvm-link</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">llvm-link</span></code>, not surprisingly, links multiple LLVM modules into a single
program.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">lli</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">lli</span></code> is the LLVM interpreter, which can directly execute LLVM bitcode
(although very slowly…). For architectures that support it (currently x86,
Sparc, and PowerPC), by default, <code class="docutils literal notranslate"><span class="pre">lli</span></code> will function as a Just-In-Time
compiler (if the functionality was compiled in), and will execute the code
<em>much</em> faster than the interpreter.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llc</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">llc</span></code> is the LLVM backend compiler, which translates LLVM bitcode to a
native code assembly file.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">opt</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">opt</span></code> reads LLVM bitcode, applies a series of LLVM to LLVM transformations
(which are specified on the command line), and outputs the resultant
bitcode. ‘<code class="docutils literal notranslate"><span class="pre">opt</span> <span class="pre">-help</span></code>’ is a good way to get a list of the
program transformations available in LLVM.</p>
<p><code class="docutils literal notranslate"><span class="pre">opt</span></code> can also run a specific analysis on an input LLVM bitcode
file and print the results. Primarily useful for debugging
analyses, or familiarizing yourself with what an analysis does.</p>
</div></blockquote>
</div>
<div class="section" id="llvm-utils">
<h3><a class="toc-backref" href="#id35"><code class="docutils literal notranslate"><span class="pre">llvm/utils</span></code></a><a class="headerlink" href="#llvm-utils" title="Permalink to this headline">¶</a></h3>
<p>Utilities for working with LLVM source code; some are part of the build process
because they are code generators for parts of the infrastructure.</p>
<p><code class="docutils literal notranslate"><span class="pre">codegen-diff</span></code></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">codegen-diff</span></code> finds differences between code that LLC
generates and code that LLI generates. This is useful if you are
debugging one of them, assuming that the other generates correct output. For
the full user manual, run <code class="docutils literal notranslate"><span class="pre">`perldoc</span> <span class="pre">codegen-diff'</span></code>.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">emacs/</span></code></p>
<blockquote>
<div><p>Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGen
description files. See the <code class="docutils literal notranslate"><span class="pre">README</span></code> for information on using them.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">getsrcs.sh</span></code></p>
<blockquote>
<div><p>Finds and outputs all non-generated source files,
useful if one wishes to do a lot of development across directories
and does not want to find each file. One way to use it is to run,
for example: <code class="docutils literal notranslate"><span class="pre">xemacs</span> <span class="pre">`utils/getsources.sh`</span></code> from the top of the LLVM source
tree.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">llvmgrep</span></code></p>
<blockquote>
<div><p>Performs an <code class="docutils literal notranslate"><span class="pre">egrep</span> <span class="pre">-H</span> <span class="pre">-n</span></code> on each source file in LLVM and
passes to it a regular expression provided on <code class="docutils literal notranslate"><span class="pre">llvmgrep</span></code>’s command
line. This is an efficient way of searching the source base for a
particular regular expression.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">TableGen/</span></code></p>
<blockquote>
<div><p>Contains the tool used to generate register
descriptions, instruction set descriptions, and even assemblers from common
TableGen description files.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">vim/</span></code></p>
<blockquote>
<div><p>vim syntax-highlighting for LLVM assembly files
and TableGen description files. See the <code class="docutils literal notranslate"><span class="pre">README</span></code> for how to use them.</p>
</div></blockquote>
</div>
</div>
<div class="section" id="an-example-using-the-llvm-tool-chain">
<span id="simple-example"></span><h2><a class="toc-backref" href="#id36">An Example Using the LLVM Tool Chain</a><a class="headerlink" href="#an-example-using-the-llvm-tool-chain" title="Permalink to this headline">¶</a></h2>
<p>This section gives an example of using LLVM with the Clang front end.</p>
<div class="section" id="example-with-clang">
<h3><a class="toc-backref" href="#id37">Example with clang</a><a class="headerlink" href="#example-with-clang" title="Permalink to this headline">¶</a></h3>
<ol class="arabic">
<li><p>First, create a simple C file, name it ‘hello.c’:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"hello world</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</li>
<li><p>Next, compile the C file into a native executable:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> clang hello.c -o hello
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Clang works just like GCC by default. The standard -S and -c arguments
work as usual (producing a native .s or .o file, respectively).</p>
</div>
</li>
<li><p>Next, compile the C file into an LLVM bitcode file:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> clang -O3 -emit-llvm hello.c -c -o hello.bc
</pre></div>
</div>
<p>The -emit-llvm option can be used with the -S or -c options to emit an LLVM
<code class="docutils literal notranslate"><span class="pre">.ll</span></code> or <code class="docutils literal notranslate"><span class="pre">.bc</span></code> file (respectively) for the code. This allows you to use
the <a class="reference external" href="CommandGuide/index.html">standard LLVM tools</a> on the bitcode file.</p>
</li>
<li><p>Run the program in both forms. To run the program, use:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> ./hello
</pre></div>
</div>
<p>and</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> lli hello.bc
</pre></div>
</div>
<p>The second examples shows how to invoke the LLVM JIT, <a class="reference internal" href="CommandGuide/lli.html"><span class="doc">lli</span></a>.</p>
</li>
<li><p>Use the <code class="docutils literal notranslate"><span class="pre">llvm-dis</span></code> utility to take a look at the LLVM assembly code:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> llvm-dis < hello.bc <span class="p">|</span> less
</pre></div>
</div>
</li>
<li><p>Compile the program to native assembly using the LLC code generator:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> llc hello.bc -o hello.s
</pre></div>
</div>
</li>
<li><p>Assemble the native assembly language file into a program:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> /opt/SUNWspro/bin/cc -xarch<span class="o">=</span>v9 hello.s -o hello.native <span class="c1"># On Solaris</span>
<span class="gp">%</span> gcc hello.s -o hello.native <span class="c1"># On others</span>
</pre></div>
</div>
</li>
<li><p>Execute the native code program:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">%</span> ./hello.native
</pre></div>
</div>
<p>Note that using clang to compile directly to native code (i.e. when the
<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code> option is not present) does steps 6/7/8 for you.</p>
</li>
</ol>
</div>
</div>
<div class="section" id="common-problems">
<h2><a class="toc-backref" href="#id38">Common Problems</a><a class="headerlink" href="#common-problems" title="Permalink to this headline">¶</a></h2>
<p>If you are having problems building or using LLVM, or if you have any other
general questions about LLVM, please consult the <a class="reference external" href="FAQ.html">Frequently Asked
Questions</a> page.</p>
<p>If you are having problems with limited memory and build time, please try
building with ninja instead of make. Please consider configuring the
following options with cmake:</p>
<blockquote>
<div><ul>
<li><p>-G Ninja
Setting this option will allow you to build with ninja instead of make.
Building with ninja significantly improves your build time, especially with
incremental builds, and improves your memory usage.</p></li>
<li><p>-DLLVM_USE_LINKER
Setting this option to lld will significantly reduce linking time for LLVM
executables on ELF-based platforms, such as Linux. If you are building LLVM
for the first time and lld is not available to you as a binary package, then
you may want to use the gold linker as a faster alternative to GNU ld.</p></li>
<li><dl class="option-list">
<dt><kbd><span class="option">-D<var>CMAKE_BUILD_TYPE</var></span></kbd></dt>
<dd><ul class="simple">
<li><p>Debug — This is the default build type. This disables optimizations while
compiling LLVM and enables debug info. On ELF-based platforms (e.g. Linux)
linking with debug info may consume a large amount of memory.</p></li>
<li><p>Release — Turns on optimizations and disables debug info. Combining the
Release build type with -DLLVM_ENABLE_ASSERTIONS=ON may be a good trade-off
between speed and debugability during development, particularly for running
the test suite.</p></li>
</ul>
</dd>
</dl>
</li>
<li><p>-DLLVM_ENABLE_ASSERTIONS
This option defaults to ON for Debug builds and defaults to OFF for Release
builds. As mentioned in the previous option, using the Release build type and
enabling assertions may be a good alternative to using the Debug build type.</p></li>
<li><p>-DLLVM_PARALLEL_LINK_JOBS
Set this equal to number of jobs you wish to run simultaneously. This is
similar to the -j option used with make, but only for link jobs. This option
can only be used with ninja. You may wish to use a very low number of jobs,
as this will greatly reduce the amount of memory used during the build
process. If you have limited memory, you may wish to set this to 1.</p></li>
<li><p>-DLLVM_TARGETS_TO_BUILD
Set this equal to the target you wish to build. You may wish to set this to
X86; however, you will find a full list of targets within the
llvm-project/llvm/lib/Target directory.</p></li>
<li><p>-DLLVM_OPTIMIZED_TABLEGEN
Set this to ON to generate a fully optimized tablegen during your build. This
will significantly improve your build time. This is only useful if you are
using the Debug build type.</p></li>
<li><p>-DLLVM_ENABLE_PROJECTS
Set this equal to the projects you wish to compile (e.g. clang, lld, etc.) If
compiling more than one project, separate the items with a semicolon. Should
you run into issues with the semicolon, try surrounding it with single quotes.</p></li>
<li><p>-DCLANG_ENABLE_STATIC_ANALYZER
Set this option to OFF if you do not require the clang static analyzer. This
should improve your build time slightly.</p></li>
<li><p>-DLLVM_USE_SPLIT_DWARF
Consider setting this to ON if you require a debug build, as this will ease
memory pressure on the linker. This will make linking much faster, as the
binaries will not contain any of the debug information; however, this will
generate the debug information in the form of a DWARF object file (with the
extension .dwo). This only applies to host platforms using ELF, such as Linux.</p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="links">
<span id="id3"></span><h2><a class="toc-backref" href="#id39">Links</a><a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h2>
<p>This document is just an <strong>introduction</strong> on how to use LLVM to do some simple
things… there are many more interesting and complicated things that you can do
that aren’t documented here (but we’ll gladly accept a patch if you want to
write something up!). For more information about LLVM, check out:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://llvm.org/">LLVM Homepage</a></p></li>
<li><p><a class="reference external" href="https://llvm.org/doxygen/">LLVM Doxygen Tree</a></p></li>
<li><p><a class="reference external" href="https://llvm.org/docs/Projects.html">Starting a Project that Uses LLVM</a></p></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
>next</a> |</li>
<li class="right" >
<a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingStartedTutorials.html" >Getting Started/Tutorials</a> »</li>
<li class="nav-item nav-item-this"><a href="">Getting Started with the LLVM System</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
