Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / bb2627d0276a34d72da6ff39d3fd5bab3668231d / . / www / get_started.html
blob: 5b7eb4dee3aea0173a4c3c5d4036c0f40e31791f [file] [log] [blame]
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]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
19<p>This page gives you the shortest path to checking out clang and demos a few
20options. This should get you up and running with the minimum of muss and fuss.
21If you like what you see, please consider <a href="get_involved.html">getting
22involved</a> with the clang community.</p>
23
24
25<h2>A word of warning</h2>
26
27<p>While this work aims to provide a fully functional C/C++/ObjC front-end, it
Gabor Greif9c63ed52008-02-28 14:59:26 +0000[diff] [blame]28is <em>still early work</em> and is under heavy development. In particular,
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]29there is no real C++ support yet (this is obviously a big project), and C/ObjC
30support is still missing some features. Some of the more notable missing pieces
31of C support are:</p>
32
33<ol>
34 <li>The semantic analyzer does not produce all of the warnings and errors it
35 should.</li>
36 <li>The LLVM code generator is still missing important features. clang is not
37 ready to be used as a general purpose C code generator yet, but if you
38 hit problems and report them to cfe-dev, we'll fix them :).</li>
39 <li>We don't consider the API to be stable yet, and reserve the right to
40 change fundamental things.</li>
41</ol>
42
43<p>Our plan is to continue chipping away at these issues until C works really
44well, but we'd love help from other interested contributors. We expect C to be
45in good shape by mid to late 2008.</p>
46
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]47<h2 id="build">Building clang / working with the code</h2>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]48
49<p>If you would like to check out and build the project, the current scheme
50is:</p>
51
52<ol>
53 <li><a href="http://www.llvm.org/docs/GettingStarted.html#checkout">Checkout
54 and build LLVM</a> from SVN head:</li>
55
56 <ul>
57 <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
58 <li><tt>cd llvm</tt></li>
59 <li><tt>./configure; make</tt></li>
60 </ul>
61 <li>Checkout clang:</li>
62 <ul>
63 <li>From within the <tt>llvm</tt> directory (where you
64 built llvm):</li>
65 <li><tt>cd llvm/tools</tt>
66 <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
67
68 </ul>
69 <li>Non-mac users: Paths to system header files are currently hard coded
70 into clang; as a result, if clang can't find your system headers,
71 please follow these instructions:</li>
72
73 <ul>
74 <li>'<tt>touch empty.c; gcc -v empty.c -fsyntax-only</tt>' to get the
75 path.</li>
76 <li>Look for the comment "FIXME: temporary hack:
77 hard-coded paths" in <tt>clang/Driver/clang.cpp</tt> and
78 change the lines below to include that path.</li>
79 </ul>
80
81 <li>Build clang:</li>
82 <ul>
83 <li><tt>cd clang</tt> (assuming that you are in <tt>llvm/tools</tt>)</li>
84 <li><tt>make</tt> (this will give you a debug build)</li>
85 </ul>
86
87 <li>Try it out (assuming you add llvm/Debug/bin to your path):</li>
88 <ul>
89 <li><tt>clang --help</tt></li>
90 <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li>
91 <li><tt>clang file.c -ast-dump</tt> (internal debug dump of ast)</li>
92 <li><tt>clang file.c -ast-view</tt> (<a
93 href="http://llvm.org/docs/ProgrammersManual.html#ViewGraph">set up graphviz
94 and rebuild llvm first</a>)</li>
95 <li><tt>clang file.c -emit-llvm</tt> (print out unoptimized llvm code)</li>
Matthijs Kooijmanddf0cad2008-06-09 14:09:10 +0000[diff] [blame]96 <li><tt>clang file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts |
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]97 llvm-dis</tt> (print out optimized llvm code)</li>
Matthijs Kooijmanddf0cad2008-06-09 14:09:10 +0000[diff] [blame]98 <li><tt>clang file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]99 &gt; file.s</tt> (output native machine code)</li>
100 </ul>
101</ol>
102
Ted Kremenek675a9ba2008-02-08 07:32:26 +0000[diff] [blame]103<p>Note that the C front-end uses LLVM, but does not depend on
104 llvm-gcc. If you encounter problems with building clang, make
105 sure you have the latest SVN version of LLVM. LLVM contains
106 support libraries for clang that will be updated as well as
107 development on clang progresses.</p>
108
Eric Christopher562b4f32008-02-08 07:10:48 +0000[diff] [blame]109<h3>Building clang while building llvm:</h3>
110 <p>Since you've checked out clang into the llvm source tree you can
111 build them all at once with a simple Makefile change. This moves
112 Step 1 above to Step 4.</p>
113 <ul>
114 <li><tt>cd llvm/tools</tt></li>
115 <li>then edit <tt>Makefile</tt> to have a clang target in <tt>PARALLEL_DIRS</tt>
116 just like <tt>llvm-config</tt></li>
117 <li>then just build llvm normally as above and clang will build at
118 the same time</li>
Gabor Greif9c63ed52008-02-28 14:59:26 +0000[diff] [blame]119 <li><em>Note:</em> you can update your toplevel project and all (possibly unrelated)
120 projects inside it with <tt><b>make update</b></tt>. This will run
121 <tt>svn update</tt> on all subdirectories related to subversion.</li>
Eric Christopher562b4f32008-02-08 07:10:48 +0000[diff] [blame]122 </ul>
123
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]124<h2>Examples of using clang</h2>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]125
126<p>The clang driver takes a lot of GCC compatible options, which you can see
127with 'clang --help'. Here are a few examples:</p>
128<!-- Thanks to
129 http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
130Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
131tag. -->
132
133<pre class="code">
134$ <b>cat ~/t.c</b>
135typedef float V __attribute__((vector_size(16)));
136V foo(V a, V b) { return a+b*a; }
137</pre>
138
139
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]140<h3>Preprocessing:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]141
142<pre class="code">
143$ <b>clang ~/t.c -E</b>
144# 1 "/Users/sabre/t.c" 1
145
146typedef float V __attribute__((vector_size(16)));
147
148V foo(V a, V b) { return a+b*a; }
149</pre>
150
151
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]152<h3>Type checking:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]153
154<pre class="code">
155$ <b>clang -fsyntax-only ~/t.c</b>
156</pre>
157
158
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]159<h3>GCC options:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]160
161<pre class="code">
162$ <b>clang -fsyntax-only ~/t.c -pedantic</b>
163/Users/sabre/t.c:2:17: warning: extension used
164typedef float V __attribute__((vector_size(16)));
165 ^
1661 diagnostic generated.
167</pre>
168
169
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]170<h3>Pretty printing from the AST:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]171
172<pre class="code">
173$ <b>clang ~/t.c -ast-print</b>
174typedef float V __attribute__(( vector_size(16) ));
175V foo(V a, V b) {
176 return a + b * a;
177}
178</pre>
179
180
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]181<h3>Code generation with LLVM:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]182
183<pre class="code">
Matthijs Kooijmanddf0cad2008-06-09 14:09:10 +0000[diff] [blame]184$ <b>clang ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llvm-dis</b>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]185define &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
186entry:
187 %mul = mul &lt;4 x float&gt; %b, %a
188 %add = add &lt;4 x float&gt; %mul, %a
189 ret &lt;4 x float&gt; %add
190}
Matthijs Kooijmanddf0cad2008-06-09 14:09:10 +0000[diff] [blame]191$ <b>clang ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=ppc32 -mcpu=g5</b>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]192..
193_foo:
194 vmaddfp v2, v3, v2, v2
195 blr
Matthijs Kooijmanddf0cad2008-06-09 14:09:10 +0000[diff] [blame]196$ <b>clang ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=x86 -mcpu=yonah</b>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]197..
198_foo:
199 mulps %xmm0, %xmm1
200 addps %xmm0, %xmm1
201 movaps %xmm1, %xmm0
202 ret
203</pre>
204
205<h3>GCC "Emulation" Driver</h3>
206
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]207<p>While the <tt>clang</tt> executable is a compiler driver that can perform
208code generation, program analysis, and other actions, it is not designed to be a
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]209drop-in replacement for GCC's <tt>cc</tt>. There is interest in developing such
210a driver for clang, but in the interim the clang source tree includes a Python
211script <tt>ccc</tt> in the <tt>utils</tt> subdirectory that provides some of
212this functionality (the script is intended to be used where GCC's <tt>cc</tt>
213could be used). It is currently a work in progress, and eventually will likely
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]214be replaced by a more complete driver.</p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]215
216<p>Example use:</p>
217
218<pre class="code">
219$ <b>ccc t.c</b>
220clang -emit-llvm-bc -o t.o -U__GNUC__ t.c
221llvm-ld -native -o a.out t.o
222$ <b>ls</b>
223a.out a.out.bc t.c t.o
224</pre>
225
226
227
228
229</div>
230</body>
231</html>