|
150
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
2 "http://www.w3.org/TR/html4/strict.dtd">
|
|
|
3 <html>
|
|
|
4 <head>
|
|
|
5 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
|
6 <title>Clang - Getting Started</title>
|
|
|
7 <link type="text/css" rel="stylesheet" href="menu.css">
|
|
|
8 <link type="text/css" rel="stylesheet" href="content.css">
|
|
|
9 </head>
|
|
|
10 <body>
|
|
|
11
|
|
|
12 <!--#include virtual="menu.html.incl"-->
|
|
|
13
|
|
|
14 <div id="content">
|
|
|
15
|
|
|
16 <h1>Getting Started: Building and Running Clang</h1>
|
|
|
17
|
|
|
18 <p>This page gives you the shortest path to checking out Clang and demos a few
|
|
|
19 options. This should get you up and running with the minimum of muss and fuss.
|
|
|
20 If you like what you see, please consider <a href="get_involved.html">getting
|
|
|
21 involved</a> with the Clang community. If you run into problems, please file
|
|
|
22 bugs in <a href="https://bugs.llvm.org/">LLVM Bugzilla</a>.</p>
|
|
|
23
|
|
|
24 <h2 id="download">Release Clang Versions</h2>
|
|
|
25
|
|
|
26 <p>Clang is released as part of regular LLVM releases. You can download the release versions from <a href="https://llvm.org/releases/">https://llvm.org/releases/</a>.</p>
|
|
|
27 <p>Clang is also provided in all major BSD or GNU/Linux distributions as part of their respective packaging systems. From Xcode 4.2, Clang is the default compiler for Mac OS X.</p>
|
|
|
28
|
|
|
29 <h2 id="build">Building Clang and Working with the Code</h2>
|
|
|
30
|
|
|
31 <h3 id="buildNix">On Unix-like Systems</h3>
|
|
|
32
|
|
|
33 <p>If you would like to check out and build Clang, the current procedure is as
|
|
|
34 follows:</p>
|
|
|
35
|
|
|
36 <ol>
|
|
|
37 <li>Get the required tools.
|
|
|
38 <ul>
|
|
|
39 <li>See
|
|
|
40 <a href="https://llvm.org/docs/GettingStarted.html#requirements">
|
|
|
41 Getting Started with the LLVM System - Requirements</a>.</li>
|
|
|
42 <li>Note also that Python is needed for running the test suite.
|
|
|
43 Get it at: <a href="https://www.python.org/downloads/">
|
|
|
44 https://www.python.org/downloads/</a></li>
|
|
|
45 <li>Standard build process uses CMake. Get it at:
|
|
|
46 <a href="https://cmake.org/download/">
|
|
|
47 https://cmake.org/download/</a></li>
|
|
|
48 </ul>
|
|
|
49
|
|
|
50 <li>Check out the LLVM project:
|
|
|
51 <ul>
|
|
|
52 <li>Change directory to where you want the llvm directory placed.</li>
|
|
|
53 <li><tt>git clone https://github.com/llvm/llvm-project.git</tt></li>
|
|
|
54 </ul>
|
|
|
55 </li>
|
|
|
56 <li>Build LLVM and Clang:
|
|
|
57 <ul>
|
|
|
58 <li><tt>cd llvm-project</tt></li>
|
|
|
59 <li><tt>mkdir build</tt> (in-tree build is not supported)</li>
|
|
|
60 <li><tt>cd build</tt></li>
|
|
|
61 <li><tt>cmake -DLLVM_ENABLE_PROJECTS=clang -G "Unix Makefiles" ../llvm</tt></li>
|
|
|
62 <li><tt>make</tt></li>
|
|
|
63 <li>This builds both LLVM and Clang for debug mode.</li>
|
|
|
64 <li>Note: For subsequent Clang development, you can just run
|
|
|
65 <tt>make clang</tt>.</li>
|
|
|
66 <li>CMake allows you to generate project files for several IDEs: Xcode,
|
|
|
67 Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator),
|
|
|
68 KDevelop3. For more details see
|
|
|
69 <a href="https://llvm.org/docs/CMake.html">Building LLVM with CMake</a>
|
|
|
70 page.</li>
|
|
|
71 </ul>
|
|
|
72 </li>
|
|
|
73
|
|
|
74 <li>If you intend to use Clang's C++ support, you may need to tell it how
|
|
|
75 to find your C++ standard library headers. In general, Clang will detect
|
|
|
76 the best version of libstdc++ headers available and use them - it will
|
|
|
77 look both for system installations of libstdc++ as well as installations
|
|
|
78 adjacent to Clang itself. If your configuration fits neither of these
|
|
|
79 scenarios, you can use the <tt>-DGCC_INSTALL_PREFIX</tt> cmake option
|
|
|
80 to tell Clang where the gcc containing the desired libstdc++ is installed.
|
|
|
81 </li>
|
|
|
82 <li>Try it out (assuming you add llvm/build/bin to your path):
|
|
|
83 <ul>
|
|
|
84 <li><tt>clang --help</tt></li>
|
|
|
85 <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li>
|
|
|
86 <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li>
|
|
|
87 <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li>
|
|
|
88 <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li>
|
|
|
89 </ul>
|
|
|
90 </li>
|
|
|
91 <li>Run the testsuite:
|
|
|
92 <ul>
|
|
|
93 <li><tt>make check-clang</tt></li>
|
|
|
94 </ul>
|
|
|
95 </li>
|
|
|
96 </ol>
|
|
|
97
|
|
|
98 <h3 id="buildWindows">Using Visual Studio</h3>
|
|
|
99
|
|
|
100 <p>The following details setting up for and building Clang on Windows using
|
|
|
101 Visual Studio:</p>
|
|
|
102
|
|
|
103 <ol>
|
|
|
104 <li>Get the required tools:
|
|
|
105 <ul>
|
|
|
106 <li><b>Git</b>. Source code control program. Get it from:
|
|
|
107 <a href="https://git-scm.com/download">
|
|
|
108 https://git-scm.com/download</a></li>
|
|
|
109 <li><b>CMake</b>. This is used for generating Visual Studio solution and
|
|
|
110 project files. Get it from:
|
|
|
111 <a href="https://cmake.org/download/">
|
|
|
112 https://cmake.org/download/</a></li>
|
|
|
113 <li><b>Visual Studio 2017 or later</b></li>
|
|
|
114 <li><b>Python</b>. It is used to run the clang test suite. Get it from:
|
|
|
115 <a href="https://www.python.org/download/">
|
|
|
116 https://www.python.org/download/</a></li>
|
|
|
117 <li><b>GnuWin32 tools</b>
|
|
|
118 The Clang and LLVM test suite use various GNU core utilities, such as
|
|
|
119 <tt>grep</tt>, <tt>sed</tt>, and <tt>find</tt>. The gnuwin32 packages
|
|
|
120 are the oldest and most well-tested way to get these tools. However, the
|
|
|
121 MSys utilities provided by git for Windows have been known to work.
|
|
|
122 Cygwin has worked in the past, but is not well tested.
|
|
|
123 If you don't already have the core utilies from some other source, get
|
|
|
124 gnuwin32 from <a href="http://getgnuwin32.sourceforge.net/">
|
|
|
125 http://getgnuwin32.sourceforge.net/</a>.</li>
|
|
|
126 </ul>
|
|
|
127 </li>
|
|
|
128
|
|
|
129 <li>Check out LLVM and Clang:
|
|
|
130 <ul>
|
|
|
131 <li><tt>git clone https://github.com/llvm/llvm-project.git</tt></li>
|
|
|
132 </ul>
|
|
|
133 <p><em>Note</em>: Some Clang tests are sensitive to the line endings. Ensure
|
|
|
134 that checking out the files does not convert LF line endings to CR+LF. If
|
|
|
135 you're using git on Windows, make sure your <tt>core.autocrlf</tt> setting
|
|
|
136 is false.</p>
|
|
|
137 </li>
|
|
|
138 <li>Run CMake to generate the Visual Studio solution and project files:
|
|
|
139 <ul>
|
|
|
140 <li><tt>cd ..\..</tt> (back to where you started)</li>
|
|
|
141 <li><tt>mkdir build</tt> (for building without polluting the source dir)</li>
|
|
|
142 <li><tt>cd build</tt></li>
|
|
|
143 <li>
|
|
|
144 If you are using Visual Studio 2017:
|
|
|
145 <tt>cmake -DLLVM_ENABLE_PROJECTS=clang -G "Visual Studio 15 2017" -A x64 -Thost=x64 ..\llvm</tt><br/>
|
|
|
146 <tt>-Thost=x64</tt> is required, since the 32-bit linker will run out of memory.
|
|
|
147 </li>
|
|
|
148 <li>To generate x86 binaries instead of x64, pass <tt>-A Win32</tt>.</li>
|
|
|
149 <li>See the <a href="https://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for
|
|
|
150 more information on other configuration options for CMake.</li>
|
|
|
151 <li>The above, if successful, will have created an LLVM.sln file in the
|
|
|
152 <tt>build</tt> directory.
|
|
|
153 </ul>
|
|
|
154 </li>
|
|
|
155 <li>Build Clang:
|
|
|
156 <ul>
|
|
|
157 <li>Open LLVM.sln in Visual Studio.</li>
|
|
|
158 <li>Build the "clang" project for just the compiler driver and front end, or
|
|
|
159 the "ALL_BUILD" project to build everything, including tools.</li>
|
|
|
160 </ul>
|
|
|
161 </li>
|
|
|
162 <li>Try it out (assuming you added llvm/debug/bin to your path). (See the
|
|
|
163 running examples from above.)</li>
|
|
|
164 <li>See <a href="hacking.html#testingWindows">
|
|
|
165 Hacking on clang - Testing using Visual Studio on Windows</a> for information
|
|
|
166 on running regression tests on Windows.</li>
|
|
|
167 </ol>
|
|
|
168
|
|
|
169 <h3 id="buildWindowsNinja">Using Ninja alongside Visual Studio</h3>
|
|
|
170
|
|
|
171 <p>We recommend that developers who want the fastest incremental builds use the
|
|
|
172 <a href="https://ninja-build.org/">Ninja build system</a>. You can use the
|
|
|
173 generated Visual Studio project files to edit Clang source code and generate a
|
|
|
174 second build directory next to it for running the tests with these steps:</p>
|
|
|
175
|
|
|
176 <ol>
|
|
|
177 <li>Check out clang and LLVM as described above</li>
|
|
|
178 <li>Open a developer command prompt with the appropriate environment.
|
|
|
179 <ul>
|
|
|
180 <li>If you open the start menu and search for "Command Prompt", you should
|
|
|
181 see shortcuts created by Visual Studio to do this. To use native x64
|
|
|
182 tools, choose the one titled "x64 Native Tools Command Prompt for VS
|
|
|
183 2017".</li>
|
|
|
184 <li> Alternatively, launch a regular <tt>cmd</tt> prompt and run the
|
|
|
185 appropriate vcvarsall.bat incantation. To get the 2017 x64 tools, this
|
|
|
186 would be:<br/>
|
|
|
187 <tt>"C:\Program Files (x86)\Microsoft Visual
|
|
|
188 Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64</tt>
|
|
|
189 </li>
|
|
|
190 </ul>
|
|
|
191 </li>
|
|
|
192 <li><tt>mkdir build_ninja</tt> (or <tt>build</tt>, or use your own
|
|
|
193 organization)</li>
|
|
|
194 <li><tt>cd build_ninja</tt></li>
|
|
|
195 <li><tt>set CC=cl</tt> (necessary to force CMake to choose MSVC over mingw GCC
|
|
|
196 if you have it installed)</li>
|
|
|
197 <li><tt>set CXX=cl</tt></li>
|
|
|
198 <li><tt>cmake -GNinja ..\llvm</tt></li>
|
|
|
199 <li><tt>ninja clang</tt> This will build just clang.</li>
|
|
|
200 <li><tt>ninja check-clang</tt> This will run the clang tests.</li>
|
|
|
201 </ol>
|
|
|
202
|
|
|
203 <h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2>
|
|
|
204
|
|
|
205 <p>The <tt>clang</tt> tool is the compiler driver and front-end, which is
|
|
|
206 designed to be a drop-in replacement for the <tt>gcc</tt> command. Here are
|
|
|
207 some examples of how to use the high-level driver:
|
|
|
208 </p>
|
|
|
209
|
|
|
210 <pre class="code">
|
|
|
211 $ <b>cat t.c</b>
|
|
|
212 #include <stdio.h>
|
|
|
213 int main(int argc, char **argv) { printf("hello world\n"); }
|
|
|
214 $ <b>clang t.c</b>
|
|
|
215 $ <b>./a.out</b>
|
|
|
216 hello world
|
|
|
217 </pre>
|
|
|
218
|
|
|
219 <p>The 'clang' driver is designed to work as closely to GCC as possible to
|
|
|
220 maximize portability. The only major difference between the two is that
|
|
|
221 Clang defaults to gnu99 mode while GCC defaults to gnu89 mode. If you see
|
|
|
222 weird link-time errors relating to inline functions, try passing -std=gnu89
|
|
|
223 to clang.</p>
|
|
|
224
|
|
|
225 <h2>Examples of using Clang</h2>
|
|
|
226
|
|
|
227 <!-- Thanks to
|
|
|
228 http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
|
|
|
229 Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
|
|
|
230 tag. -->
|
|
|
231
|
|
|
232 <pre class="code">
|
|
|
233 $ <b>cat ~/t.c</b>
|
|
|
234 typedef float V __attribute__((vector_size(16)));
|
|
|
235 V foo(V a, V b) { return a+b*a; }
|
|
|
236 </pre>
|
|
|
237
|
|
|
238
|
|
|
239 <h3>Preprocessing:</h3>
|
|
|
240
|
|
|
241 <pre class="code">
|
|
|
242 $ <b>clang ~/t.c -E</b>
|
|
|
243 # 1 "/Users/sabre/t.c" 1
|
|
|
244
|
|
|
245 typedef float V __attribute__((vector_size(16)));
|
|
|
246
|
|
|
247 V foo(V a, V b) { return a+b*a; }
|
|
|
248 </pre>
|
|
|
249
|
|
|
250
|
|
|
251 <h3>Type checking:</h3>
|
|
|
252
|
|
|
253 <pre class="code">
|
|
|
254 $ <b>clang -fsyntax-only ~/t.c</b>
|
|
|
255 </pre>
|
|
|
256
|
|
|
257
|
|
|
258 <h3>GCC options:</h3>
|
|
|
259
|
|
|
260 <pre class="code">
|
|
|
261 $ <b>clang -fsyntax-only ~/t.c -pedantic</b>
|
|
|
262 /Users/sabre/t.c:2:17: <span style="color:magenta">warning:</span> extension used
|
|
|
263 <span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span>
|
|
|
264 <span style="color:blue"> ^</span>
|
|
|
265 1 diagnostic generated.
|
|
|
266 </pre>
|
|
|
267
|
|
|
268
|
|
|
269 <h3>Pretty printing from the AST:</h3>
|
|
|
270
|
|
|
271 <p>Note, the <tt>-cc1</tt> argument indicates the compiler front-end, and
|
|
|
272 not the driver, should be run. The compiler front-end has several additional
|
|
|
273 Clang specific features which are not exposed through the GCC compatible driver
|
|
|
274 interface.</p>
|
|
|
275
|
|
|
276 <pre class="code">
|
|
|
277 $ <b>clang -cc1 ~/t.c -ast-print</b>
|
|
|
278 typedef float V __attribute__(( vector_size(16) ));
|
|
|
279 V foo(V a, V b) {
|
|
|
280 return a + b * a;
|
|
|
281 }
|
|
|
282 </pre>
|
|
|
283
|
|
|
284
|
|
|
285 <h3>Code generation with LLVM:</h3>
|
|
|
286
|
|
|
287 <pre class="code">
|
|
|
288 $ <b>clang ~/t.c -S -emit-llvm -o -</b>
|
|
|
289 define <4 x float> @foo(<4 x float> %a, <4 x float> %b) {
|
|
|
290 entry:
|
|
|
291 %mul = mul <4 x float> %b, %a
|
|
|
292 %add = add <4 x float> %mul, %a
|
|
|
293 ret <4 x float> %add
|
|
|
294 }
|
|
|
295 $ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i>
|
|
|
296 ...
|
|
|
297 _foo:
|
|
|
298 Leh_func_begin1:
|
|
|
299 mulps %xmm0, %xmm1
|
|
|
300 addps %xmm1, %xmm0
|
|
|
301 ret
|
|
|
302 Leh_func_end1:
|
|
|
303 </pre>
|
|
|
304
|
|
|
305 </div>
|
|
|
306 </body>
|
|
|
307 </html>
|
