Clang Project

clang_source_code/www/get_started.html
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
19options.  This should get you up and running with the minimum of muss and fuss.
20If you like what you see, please consider <a href="get_involved.html">getting
21involved</a> with the Clang community.  If you run into problems, please file
22bugs 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
34follows:</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="http://www.python.org/download">
44      http://www.python.org/download</a></li>
45    <li>Standard build process uses CMake. Get it at:
46      <a href="http://www.cmake.org/download">
47      http://www.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
101Visual 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 2015 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
173generated Visual Studio project files to edit Clang source code and generate a
174second 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
206designed to be a drop-in replacement for the <tt>gcc</tt> command.  Here are
207some examples of how to use the high-level driver:
208</p>
209
210<pre class="code">
211$ <b>cat t.c</b>
212#include &lt;stdio.h&gt;
213int main(int argc, char **argv) { printf("hello world\n"); }
214$ <b>clang t.c</b>
215$ <b>./a.out</b>
216hello 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
229Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
230tag. -->
231
232<pre class="code">
233$ <b>cat ~/t.c</b>
234typedef float V __attribute__((vector_size(16)));
235V 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
245typedef float V __attribute__((vector_size(16)));
246
247V 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>
2651 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
272not the driver, should be run. The compiler front-end has several additional
273Clang specific features which are not exposed through the GCC compatible driver
274interface.</p>
275
276<pre class="code">
277$ <b>clang -cc1 ~/t.c -ast-print</b>
278typedef float V __attribute__(( vector_size(16) ));
279V 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>
289define &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
290entry:
291         %mul = mul &lt;4 x float&gt; %b, %a
292         %add = add &lt;4 x float&gt; %mul, %a
293         ret &lt;4 x float&gt; %add
294}
295$ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i>
296...
297_foo:
298Leh_func_begin1:
299 mulps %xmm0, %xmm1
300 addps %xmm1, %xmm0
301 ret
302Leh_func_end1:
303</pre>
304
305</div>
306</body>
307</html>
308
CodeThinker, Enjoy your reading code