Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 675a9ba538da9fec1e0db0c285076fe022f28d75 / . / www / get_started.html
blob: 950f449751dc0879c37427265b5a711a821d30fc [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
28is <em>still very early work</em> and is under heavy development. In particular,
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
47<h3><a name="build">Building clang / working with the code</a></h3>
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>
96 <li><tt>clang file.c -emit-llvm | llvm-as | opt -std-compile-opts |
97 llvm-dis</tt> (print out optimized llvm code)</li>
98 <li><tt>clang file.c -emit-llvm | llvm-as | opt -std-compile-opts | llc
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>
119 </ul>
120
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]121<h3>Examples of using clang</h3>
122
123<p>The clang driver takes a lot of GCC compatible options, which you can see
124with 'clang --help'. Here are a few examples:</p>
125<!-- Thanks to
126 http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
127Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
128tag. -->
129
130<pre class="code">
131$ <b>cat ~/t.c</b>
132typedef float V __attribute__((vector_size(16)));
133V foo(V a, V b) { return a+b*a; }
134</pre>
135
136
137<h4>Preprocessing:</h4>
138
139<pre class="code">
140$ <b>clang ~/t.c -E</b>
141# 1 "/Users/sabre/t.c" 1
142
143typedef float V __attribute__((vector_size(16)));
144
145V foo(V a, V b) { return a+b*a; }
146</pre>
147
148
149<h4>Type checking:</h4>
150
151<pre class="code">
152$ <b>clang -fsyntax-only ~/t.c</b>
153</pre>
154
155
156<h4>GCC options:</h4>
157
158<pre class="code">
159$ <b>clang -fsyntax-only ~/t.c -pedantic</b>
160/Users/sabre/t.c:2:17: warning: extension used
161typedef float V __attribute__((vector_size(16)));
162 ^
1631 diagnostic generated.
164</pre>
165
166
167<h4>Pretty printing from the AST:</h4>
168
169<pre class="code">
170$ <b>clang ~/t.c -ast-print</b>
171typedef float V __attribute__(( vector_size(16) ));
172V foo(V a, V b) {
173 return a + b * a;
174}
175</pre>
176
177
178<h4>Code generation with LLVM:</h4>
179
180<pre class="code">
181$ <b>clang ~/t.c -emit-llvm | llvm-as | opt -std-compile-opts | llvm-dis</b>
182define &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
183entry:
184 %mul = mul &lt;4 x float&gt; %b, %a
185 %add = add &lt;4 x float&gt; %mul, %a
186 ret &lt;4 x float&gt; %add
187}
188$ <b>clang ~/t.c -emit-llvm | llvm-as | opt -std-compile-opts | llc -march=ppc32 -mcpu=g5</b>
189..
190_foo:
191 vmaddfp v2, v3, v2, v2
192 blr
193$ <b>clang ~/t.c -emit-llvm | llvm-as | opt -std-compile-opts | llc -march=x86 -mcpu=yonah</b>
194..
195_foo:
196 mulps %xmm0, %xmm1
197 addps %xmm0, %xmm1
198 movaps %xmm1, %xmm0
199 ret
200</pre>
201
202<h3>GCC "Emulation" Driver</h3>
203
204While the <tt>clang</tt> executable is a compiler driver that can perform code
205generation, program analysis, and other actions, it is not designed to be a
206drop-in replacement for GCC's <tt>cc</tt>. There is interest in developing such
207a driver for clang, but in the interim the clang source tree includes a Python
208script <tt>ccc</tt> in the <tt>utils</tt> subdirectory that provides some of
209this functionality (the script is intended to be used where GCC's <tt>cc</tt>
210could be used). It is currently a work in progress, and eventually will likely
211be replaced by a more complete driver.
212
213<p>Example use:</p>
214
215<pre class="code">
216$ <b>ccc t.c</b>
217clang -emit-llvm-bc -o t.o -U__GNUC__ t.c
218llvm-ld -native -o a.out t.o
219$ <b>ls</b>
220a.out a.out.bc t.c t.o
221</pre>
222
223
224
225
226</div>
227</body>
228</html>