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