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