xref: /aosp_15_r20/external/clang/www/get_started.html (revision 67e74705e28f6214e480b399dd47ea732279e315) 
1*67e74705SXin Li<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2*67e74705SXin Li          "http://www.w3.org/TR/html4/strict.dtd">
3*67e74705SXin Li<html>
4*67e74705SXin Li<head>
5*67e74705SXin Li  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6*67e74705SXin Li  <title>Clang - Getting Started</title>
7*67e74705SXin Li  <link type="text/css" rel="stylesheet" href="menu.css">
8*67e74705SXin Li  <link type="text/css" rel="stylesheet" href="content.css">
9*67e74705SXin Li</head>
10*67e74705SXin Li<body>
11*67e74705SXin Li
12*67e74705SXin Li<!--#include virtual="menu.html.incl"-->
13*67e74705SXin Li
14*67e74705SXin Li<div id="content">
15*67e74705SXin Li
16*67e74705SXin Li<h1>Getting Started: Building and Running Clang</h1>
17*67e74705SXin Li
18*67e74705SXin Li<p>This page gives you the shortest path to checking out Clang and demos a few
19*67e74705SXin Lioptions.  This should get you up and running with the minimum of muss and fuss.
20*67e74705SXin LiIf you like what you see, please consider <a href="get_involved.html">getting
21*67e74705SXin Liinvolved</a> with the Clang community.  If you run into problems, please file
22*67e74705SXin Libugs in <a href="http://llvm.org/bugs/">LLVM Bugzilla</a>.</p>
23*67e74705SXin Li
24*67e74705SXin Li<h2 id="download">Release Clang Versions</h2>
25*67e74705SXin Li
26*67e74705SXin Li<p>Clang is released as part of regular LLVM releases. You can download the release versions from <a href="http://llvm.org/releases/">http://llvm.org/releases/</a>.</p>
27*67e74705SXin Li<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*67e74705SXin Li
29*67e74705SXin Li<h2 id="build">Building Clang and Working with the Code</h2>
30*67e74705SXin Li
31*67e74705SXin Li<h3 id="buildNix">On Unix-like Systems</h3>
32*67e74705SXin Li
33*67e74705SXin Li<p>If you would like to check out and build Clang, the current procedure is as
34*67e74705SXin Lifollows:</p>
35*67e74705SXin Li
36*67e74705SXin Li<ol>
37*67e74705SXin Li  <li>Get the required tools.
38*67e74705SXin Li  <ul>
39*67e74705SXin Li    <li>See
40*67e74705SXin Li      <a href="http://llvm.org/docs/GettingStarted.html#requirements">
41*67e74705SXin Li      Getting Started with the LLVM System - Requirements</a>.</li>
42*67e74705SXin Li    <li>Note also that Python is needed for running the test suite.
43*67e74705SXin Li      Get it at: <a href="http://www.python.org/download">
44*67e74705SXin Li      http://www.python.org/download</a></li>
45*67e74705SXin Li    <li>Standard build process uses CMake. Get it at:
46*67e74705SXin Li      <a href="http://www.cmake.org/download">
47*67e74705SXin Li      http://www.cmake.org/download</a></li>
48*67e74705SXin Li  </ul>
49*67e74705SXin Li
50*67e74705SXin Li  <li>Check out LLVM:
51*67e74705SXin Li  <ul>
52*67e74705SXin Li    <li>Change directory to where you want the llvm directory placed.</li>
53*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
54*67e74705SXin Li  </ul>
55*67e74705SXin Li  </li>
56*67e74705SXin Li  <li>Check out Clang:
57*67e74705SXin Li  <ul>
58*67e74705SXin Li    <li><tt>cd llvm/tools</tt></li>
59*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
60*67e74705SXin Li    <li><tt>cd ../..</tt></li>
61*67e74705SXin Li  </ul>
62*67e74705SXin Li  </li>
63*67e74705SXin Li  <li>Check out extra Clang tools: (optional)
64*67e74705SXin Li  <ul>
65*67e74705SXin Li    <li><tt>cd llvm/tools/clang/tools</tt></li>
66*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk
67*67e74705SXin Li        extra</tt></li>
68*67e74705SXin Li    <li><tt>cd ../../../..</tt></li>
69*67e74705SXin Li  </ul>
70*67e74705SXin Li  </li>
71*67e74705SXin Li  <li>Check out Compiler-RT (optional):
72*67e74705SXin Li  <ul>
73*67e74705SXin Li    <li><tt>cd llvm/projects</tt></li>
74*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk
75*67e74705SXin Li        compiler-rt</tt></li>
76*67e74705SXin Li    <li><tt>cd ../..</tt></li>
77*67e74705SXin Li  </ul>
78*67e74705SXin Li  </li>
79*67e74705SXin Li  <li>Check out libcxx: (only required to build and run Compiler-RT tests on OS X, optional otherwise)
80*67e74705SXin Li  <ul>
81*67e74705SXin Li    <li><tt>cd llvm/projects</tt></li>
82*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/libcxx/trunk
83*67e74705SXin Li        libcxx</tt></li>
84*67e74705SXin Li    <li><tt>cd ../..</tt></li>
85*67e74705SXin Li  </ul>
86*67e74705SXin Li  </li>
87*67e74705SXin Li  <li>Build LLVM and Clang:
88*67e74705SXin Li  <ul>
89*67e74705SXin Li    <li><tt>mkdir build</tt> (in-tree build is not supported)</li>
90*67e74705SXin Li    <li><tt>cd build</tt></li>
91*67e74705SXin Li    <li><tt>cmake -G "Unix Makefiles" ../llvm</tt></li>
92*67e74705SXin Li    <li><tt>make</tt></li>
93*67e74705SXin Li    <li>This builds both LLVM and Clang for debug mode.</li>
94*67e74705SXin Li    <li>Note: For subsequent Clang development, you can just run
95*67e74705SXin Li        <tt>make clang</tt>.</li>
96*67e74705SXin Li    <li>CMake allows you to generate project files for several IDEs: Xcode,
97*67e74705SXin Li        Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator),
98*67e74705SXin Li        KDevelop3. For more details see
99*67e74705SXin Li        <a href="http://llvm.org/docs/CMake.html">Building LLVM with CMake</a>
100*67e74705SXin Li        page.</li>
101*67e74705SXin Li  </ul>
102*67e74705SXin Li  </li>
103*67e74705SXin Li
104*67e74705SXin Li  <li>If you intend to use Clang's C++ support, you may need to tell it how
105*67e74705SXin Li      to find your C++ standard library headers. In general, Clang will detect
106*67e74705SXin Li      the best version of libstdc++ headers available and use them - it will
107*67e74705SXin Li      look both for system installations of libstdc++ as well as installations
108*67e74705SXin Li      adjacent to Clang itself. If your configuration fits neither of these
109*67e74705SXin Li      scenarios, you can use the <tt>-DGCC_INSTALL_PREFIX</tt> cmake option
110*67e74705SXin Li      to tell Clang where the gcc containing the desired libstdc++ is installed.
111*67e74705SXin Li  </li>
112*67e74705SXin Li  <li>Try it out (assuming you add llvm/build/bin to your path):
113*67e74705SXin Li  <ul>
114*67e74705SXin Li    <li><tt>clang --help</tt></li>
115*67e74705SXin Li    <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li>
116*67e74705SXin Li    <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li>
117*67e74705SXin Li    <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li>
118*67e74705SXin Li    <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li>
119*67e74705SXin Li  </ul>
120*67e74705SXin Li  </li>
121*67e74705SXin Li</ol>
122*67e74705SXin Li
123*67e74705SXin Li<p>If you encounter problems while building Clang, make sure that your LLVM
124*67e74705SXin Licheckout is at the same revision as your Clang checkout. LLVM's interfaces
125*67e74705SXin Lichange over time, and mismatched revisions are not expected to work
126*67e74705SXin Litogether.</p>
127*67e74705SXin Li
128*67e74705SXin Li<h3>Simultaneously Building Clang and LLVM:</h3>
129*67e74705SXin Li
130*67e74705SXin Li<p>Once you have checked out Clang into the llvm source tree it will build along
131*67e74705SXin Liwith the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at
132*67e74705SXin Lionce simply run <tt>make</tt> from the root LLVM directory.</p>
133*67e74705SXin Li
134*67e74705SXin Li<p><em>Note:</em> Observe that Clang is technically part of a separate
135*67e74705SXin LiSubversion repository. As mentioned above, the latest Clang sources are tied to
136*67e74705SXin Lithe latest sources in the LLVM tree. You can update your toplevel LLVM project
137*67e74705SXin Liand all (possibly unrelated) projects inside it with <tt><b>make
138*67e74705SXin Liupdate</b></tt>. This will run <tt>svn update</tt> on all subdirectories related
139*67e74705SXin Lito subversion. </p>
140*67e74705SXin Li
141*67e74705SXin Li<h3 id="buildWindows">Using Visual Studio</h3>
142*67e74705SXin Li
143*67e74705SXin Li<p>The following details setting up for and building Clang on Windows using
144*67e74705SXin LiVisual Studio:</p>
145*67e74705SXin Li
146*67e74705SXin Li<ol>
147*67e74705SXin Li  <li>Get the required tools:
148*67e74705SXin Li  <ul>
149*67e74705SXin Li    <li><b>Subversion</b>.  Source code control program.  Get it from:
150*67e74705SXin Li        <a href="http://subversion.apache.org/packages.html">
151*67e74705SXin Li        http://subversion.apache.org/packages.html</a></li>
152*67e74705SXin Li    <li><b>CMake</b>.  This is used for generating Visual Studio solution and
153*67e74705SXin Li        project files.  Get it from:
154*67e74705SXin Li        <a href="http://www.cmake.org/cmake/resources/software.html">
155*67e74705SXin Li        http://www.cmake.org/cmake/resources/software.html</a></li>
156*67e74705SXin Li    <li><b>Visual Studio 2013 or later</b></li>
157*67e74705SXin Li    <li><b>Python</b>.  This is needed only if you will be running the tests
158*67e74705SXin Li        (which is essential, if you will be developing for clang).
159*67e74705SXin Li        Get it from:
160*67e74705SXin Li        <a href="http://www.python.org/download/">
161*67e74705SXin Li        http://www.python.org/download/</a></li>
162*67e74705SXin Li    <li><b>GnuWin32 tools</b>
163*67e74705SXin Li        These are also necessary for running the tests.
164*67e74705SXin Li        (Note that the grep from MSYS or Cygwin doesn't work with the tests
165*67e74705SXin Li        because of embedded double-quotes in the search strings.  The GNU
166*67e74705SXin Li        grep does work in this case.)
167*67e74705SXin Li        Get them from <a href="http://getgnuwin32.sourceforge.net/">
168*67e74705SXin Li        http://getgnuwin32.sourceforge.net/</a>.</li>
169*67e74705SXin Li  </ul>
170*67e74705SXin Li  </li>
171*67e74705SXin Li
172*67e74705SXin Li  <li>Check out LLVM:
173*67e74705SXin Li  <ul>
174*67e74705SXin Li    <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
175*67e74705SXin Li  </ul>
176*67e74705SXin Li  </li>
177*67e74705SXin Li  <li>Check out Clang:
178*67e74705SXin Li  <ul>
179*67e74705SXin Li     <li><tt>cd llvm\tools</tt>
180*67e74705SXin Li     <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
181*67e74705SXin Li  </ul>
182*67e74705SXin Li  <p><em>Note</em>:  Some Clang tests are sensitive to the line endings.  Ensure
183*67e74705SXin Li     that checking out the files does not convert LF line endings to CR+LF.
184*67e74705SXin Li     If you use git-svn, make sure your <tt>core.autocrlf</tt> setting is false.</p>
185*67e74705SXin Li  </li>
186*67e74705SXin Li  <li>Run CMake to generate the Visual Studio solution and project files:
187*67e74705SXin Li  <ul>
188*67e74705SXin Li    <li><tt>cd ..\..</tt>  (back to where you started)</li>
189*67e74705SXin Li    <li><tt>mkdir build</tt> (for building without polluting the source dir)</li>
190*67e74705SXin Li    <li><tt>cd build</tt></li>
191*67e74705SXin Li    <li>If you are using Visual Studio 2013:  <tt>cmake -G "Visual Studio 12" ..\llvm</tt></li>
192*67e74705SXin Li    <li>See the <a href="http://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for
193*67e74705SXin Li        more information on other configuration options for CMake.</li>
194*67e74705SXin Li    <li>The above, if successful, will have created an LLVM.sln file in the
195*67e74705SXin Li       <tt>build</tt> directory.
196*67e74705SXin Li  </ul>
197*67e74705SXin Li  </li>
198*67e74705SXin Li  <li>Build Clang:
199*67e74705SXin Li  <ul>
200*67e74705SXin Li    <li>Open LLVM.sln in Visual Studio.</li>
201*67e74705SXin Li    <li>Build the "clang" project for just the compiler driver and front end, or
202*67e74705SXin Li      the "ALL_BUILD" project to build everything, including tools.</li>
203*67e74705SXin Li  </ul>
204*67e74705SXin Li  </li>
205*67e74705SXin Li  <li>Try it out (assuming you added llvm/debug/bin to your path).  (See the
206*67e74705SXin Li    running examples from above.)</li>
207*67e74705SXin Li  <li>See <a href="hacking.html#testingWindows">
208*67e74705SXin Li     Hacking on clang - Testing using Visual Studio on Windows</a> for information
209*67e74705SXin Li     on running regression tests on Windows.</li>
210*67e74705SXin Li</ol>
211*67e74705SXin Li
212*67e74705SXin Li<p>Note that once you have checked out both llvm and clang, to synchronize
213*67e74705SXin Lito the latest code base, use the <tt>svn update</tt> command in both the
214*67e74705SXin Lillvm and llvm\tools\clang directories, as they are separate repositories.</p>
215*67e74705SXin Li
216*67e74705SXin Li<h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2>
217*67e74705SXin Li
218*67e74705SXin Li<p>The <tt>clang</tt> tool is the compiler driver and front-end, which is
219*67e74705SXin Lidesigned to be a drop-in replacement for the <tt>gcc</tt> command.  Here are
220*67e74705SXin Lisome examples of how to use the high-level driver:
221*67e74705SXin Li</p>
222*67e74705SXin Li
223*67e74705SXin Li<pre class="code">
224*67e74705SXin Li$ <b>cat t.c</b>
225*67e74705SXin Li#include &lt;stdio.h&gt;
226*67e74705SXin Liint main(int argc, char **argv) { printf("hello world\n"); }
227*67e74705SXin Li$ <b>clang t.c</b>
228*67e74705SXin Li$ <b>./a.out</b>
229*67e74705SXin Lihello world
230*67e74705SXin Li</pre>
231*67e74705SXin Li
232*67e74705SXin Li<p>The 'clang' driver is designed to work as closely to GCC as possible to
233*67e74705SXin Li  maximize portability.  The only major difference between the two is that
234*67e74705SXin Li  Clang defaults to gnu99 mode while GCC defaults to gnu89 mode.  If you see
235*67e74705SXin Li  weird link-time errors relating to inline functions, try passing -std=gnu89
236*67e74705SXin Li  to clang.</p>
237*67e74705SXin Li
238*67e74705SXin Li<h2>Examples of using Clang</h2>
239*67e74705SXin Li
240*67e74705SXin Li<!-- Thanks to
241*67e74705SXin Li http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
242*67e74705SXin LiSite suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
243*67e74705SXin Litag. -->
244*67e74705SXin Li
245*67e74705SXin Li<pre class="code">
246*67e74705SXin Li$ <b>cat ~/t.c</b>
247*67e74705SXin Litypedef float V __attribute__((vector_size(16)));
248*67e74705SXin LiV foo(V a, V b) { return a+b*a; }
249*67e74705SXin Li</pre>
250*67e74705SXin Li
251*67e74705SXin Li
252*67e74705SXin Li<h3>Preprocessing:</h3>
253*67e74705SXin Li
254*67e74705SXin Li<pre class="code">
255*67e74705SXin Li$ <b>clang ~/t.c -E</b>
256*67e74705SXin Li# 1 "/Users/sabre/t.c" 1
257*67e74705SXin Li
258*67e74705SXin Litypedef float V __attribute__((vector_size(16)));
259*67e74705SXin Li
260*67e74705SXin LiV foo(V a, V b) { return a+b*a; }
261*67e74705SXin Li</pre>
262*67e74705SXin Li
263*67e74705SXin Li
264*67e74705SXin Li<h3>Type checking:</h3>
265*67e74705SXin Li
266*67e74705SXin Li<pre class="code">
267*67e74705SXin Li$ <b>clang -fsyntax-only ~/t.c</b>
268*67e74705SXin Li</pre>
269*67e74705SXin Li
270*67e74705SXin Li
271*67e74705SXin Li<h3>GCC options:</h3>
272*67e74705SXin Li
273*67e74705SXin Li<pre class="code">
274*67e74705SXin Li$ <b>clang -fsyntax-only ~/t.c -pedantic</b>
275*67e74705SXin Li/Users/sabre/t.c:2:17: <span style="color:magenta">warning:</span> extension used
276*67e74705SXin Li<span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span>
277*67e74705SXin Li<span style="color:blue">                ^</span>
278*67e74705SXin Li1 diagnostic generated.
279*67e74705SXin Li</pre>
280*67e74705SXin Li
281*67e74705SXin Li
282*67e74705SXin Li<h3>Pretty printing from the AST:</h3>
283*67e74705SXin Li
284*67e74705SXin Li<p>Note, the <tt>-cc1</tt> argument indicates the compiler front-end, and
285*67e74705SXin Linot the driver, should be run. The compiler front-end has several additional
286*67e74705SXin LiClang specific features which are not exposed through the GCC compatible driver
287*67e74705SXin Liinterface.</p>
288*67e74705SXin Li
289*67e74705SXin Li<pre class="code">
290*67e74705SXin Li$ <b>clang -cc1 ~/t.c -ast-print</b>
291*67e74705SXin Litypedef float V __attribute__(( vector_size(16) ));
292*67e74705SXin LiV foo(V a, V b) {
293*67e74705SXin Li   return a + b * a;
294*67e74705SXin Li}
295*67e74705SXin Li</pre>
296*67e74705SXin Li
297*67e74705SXin Li
298*67e74705SXin Li<h3>Code generation with LLVM:</h3>
299*67e74705SXin Li
300*67e74705SXin Li<pre class="code">
301*67e74705SXin Li$ <b>clang ~/t.c -S -emit-llvm -o -</b>
302*67e74705SXin Lidefine &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
303*67e74705SXin Lientry:
304*67e74705SXin Li         %mul = mul &lt;4 x float&gt; %b, %a
305*67e74705SXin Li         %add = add &lt;4 x float&gt; %mul, %a
306*67e74705SXin Li         ret &lt;4 x float&gt; %add
307*67e74705SXin Li}
308*67e74705SXin Li$ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i>
309*67e74705SXin Li...
310*67e74705SXin Li_foo:
311*67e74705SXin LiLeh_func_begin1:
312*67e74705SXin Li	mulps	%xmm0, %xmm1
313*67e74705SXin Li	addps	%xmm1, %xmm0
314*67e74705SXin Li	ret
315*67e74705SXin LiLeh_func_end1:
316*67e74705SXin Li</pre>
317*67e74705SXin Li
318*67e74705SXin Li</div>
319*67e74705SXin Li</body>
320*67e74705SXin Li</html>
321