Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / dc8c90da158030c0d0c62539e2da0adccc09f271 / . / www / get_started.html
blob: 1393981c5b30d6d661967735b23ba67609a2f2e0 [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
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]18<p>This page gives you the shortest path to checking out Clang and demos a few
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]19options. This should get you up and running with the minimum of muss and fuss.
20If you like what you see, please consider <a href="get_involved.html">getting
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]21involved</a> with the Clang community.</p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]22
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]23<h2>A Word of Warning</h2>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]24
25<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]26is <em>still early work</em> and is under heavy development. In particular,
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]27there 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]28support is still missing some minor features. Some of the more notable missing
29pieces of C support are:</p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]30
31<ol>
Chris Lattnerd8258832009-02-25 05:35:47 +0000[diff] [blame]32 <li>The semantic analyzer does not produce all of the warnings it should.</li>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]33 <li>We don't consider the API to be stable yet, and reserve the right to
34 change fundamental things.</li>
Chris Lattnerd8258832009-02-25 05:35:47 +0000[diff] [blame]35 <li>The driver is currently implemented in python and is "really slow".</li>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]36</ol>
37
Chris Lattnerd8258832009-02-25 05:35:47 +0000[diff] [blame]38<p>At this point, C and Objective-C are generally usable for X86-32 and X86-64
39targets. If you run into problems, please file bugs in <a
40href="http://llvm.org/bugs/">LLVM Bugzilla</a> or bring up the issue on the
41<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang development
42mailing list</a>.</p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]43
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]44<h2 id="build">Building Clang and Working with the Code</h2>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]45
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]46<p>If you would like to check out and build Clang, the current procedure is as
47follows:</p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]48
49<ol>
50 <li><a href="http://www.llvm.org/docs/GettingStarted.html#checkout">Checkout
51 and build LLVM</a> from SVN head:</li>
52
53 <ul>
54 <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
55 <li><tt>cd llvm</tt></li>
56 <li><tt>./configure; make</tt></li>
57 </ul>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]58 <li>Checkout Clang:</li>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]59 <ul>
60 <li>From within the <tt>llvm</tt> directory (where you
61 built llvm):</li>
Ted Kremenek8c22bc32008-07-14 14:40:22 +0000[diff] [blame]62 <li><tt>cd tools</tt>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]63 <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
64
65 </ul>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]66 <li>If you intend to work on Clang C++ support, you may need to tell it how
67 to find your C++ standard library headers. If Clang cannot find your
Chris Lattnerca8c49f2009-03-10 16:01:44 +0000[diff] [blame]68 system libstdc++ headers, please follow these instructions:</li>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]69
70 <ul>
Chris Lattnerca8c49f2009-03-10 16:01:44 +0000[diff] [blame]71 <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]72 path.</li>
73 <li>Look for the comment "FIXME: temporary hack:
Chris Lattnerca8c49f2009-03-10 16:01:44 +0000[diff] [blame]74 hard-coded paths" in <tt>clang/lib/Frontend/InitHeaderSearch.cpp</tt> and
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]75 change the lines below to include that path.</li>
76 </ul>
77
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]78 <li>Build Clang:</li>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]79 <ul>
80 <li><tt>cd clang</tt> (assuming that you are in <tt>llvm/tools</tt>)</li>
81 <li><tt>make</tt> (this will give you a debug build)</li>
82 </ul>
83
84 <li>Try it out (assuming you add llvm/Debug/bin to your path):</li>
85 <ul>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]86 <li><tt>clang-cc --help</tt></li>
87 <li><tt>clang-cc file.c -fsyntax-only</tt> (check for correctness)</li>
88 <li><tt>clang-cc file.c -ast-dump</tt> (internal debug dump of ast)</li>
89 <li><tt>clang-cc file.c -ast-view</tt> (<a
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]90 href="http://llvm.org/docs/ProgrammersManual.html#ViewGraph">set up graphviz
91 and rebuild llvm first</a>)</li>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]92 <li><tt>clang-cc file.c -emit-llvm</tt> (print out unoptimized llvm code)</li>
93 <li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts |
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]94 llvm-dis</tt> (print out optimized llvm code)</li>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]95 <li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]96 &gt; file.s</tt> (output native machine code)</li>
97 </ul>
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]98
99 <p><em>Note</em>: Here <tt>clang-cc</tt> is the "low-level" frontend
100 executable that is similar in purpose to <tt>cc1</tt>. Clang also has a <a
101 href="#driver">high-level compiler driver</a> that acts as a drop-in
102 replacement for <tt>gcc</tt>.
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]103</ol>
104
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]105<p>Note that the C front-end uses LLVM, but does not depend on llvm-gcc. If you
106encounter problems with building Clang, make sure you have the latest SVN
107version of LLVM. LLVM contains support libraries for Clang that will be updated
108as well as development on Clang progresses.</p>
Ted Kremenek675a9ba2008-02-08 07:32:26 +0000[diff] [blame]109
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]110<h3>Simultaneously Building Clang and LLVM:</h3>
Eric Christopher562b4f32008-02-08 07:10:48 +0000[diff] [blame]111
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]112<p>Once you have checked out Clang into the llvm source tree it will build along
113with the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at
114once simply run <tt>make</tt> from the root LLVM directory.</p>
115
116<p><em>Note:</em> Observe that Clang is technically part of a separate
117Subversion repository. As mentioned above, the latest Clang sources are tied to
118the latest sources in the LLVM tree. You can update your toplevel LLVM project
119and all (possibly unrelated) projects inside it with <tt><b>make
120update</b></tt>. This will run <tt>svn update</tt> on all subdirectories related
121to subversion. </p>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]122
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]123<a name="driver"><h2>High-Level Compiler Driver (Drop-in Substitute for GCC)</h2></a>
124
125<p>While the <tt>clang-cc</tt> executable is a low-level frontend executable
126that can perform code generation, program analysis, and other actions, it is not
127designed to be a drop-in replacement for GCC's <tt>cc</tt>. For this purpose,
128use the high-level driver, aptly named <tt>clang</tt>. Here are some
129examples of how to use the high-level driver:
130</p>
131
132<pre class="code">
133$ <b>cat t.c</b>
134#include &lt;stdio.h&gt;
135int main(int argc, char **argv) { printf("hello world\n"); }
136$ <b>clang t.c</b>
137$ <b>./a.out</b>
138hello world
139</pre>
140
141<h2>Examples of using Clang</h2>
142
143<p>The high-level driver <tt>clang</tt> is designed to understand most of GCC's
144options, and the lower-level <tt>clang-cc</tt> executable also directly takes
145many of GCC's options. You can see which options <tt>clang-cc</tt> accepts with
146'<tt>clang-cc --help</tt>'. Here are a few examples of using <tt>clang</tt> and
147<tt>clang-cc</tt>:</p>
148
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]149<!-- Thanks to
150 http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
151Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
152tag. -->
153
154<pre class="code">
155$ <b>cat ~/t.c</b>
156typedef float V __attribute__((vector_size(16)));
157V foo(V a, V b) { return a+b*a; }
158</pre>
159
160
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]161<h3>Preprocessing:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]162
163<pre class="code">
164$ <b>clang ~/t.c -E</b>
165# 1 "/Users/sabre/t.c" 1
166
167typedef float V __attribute__((vector_size(16)));
168
169V foo(V a, V b) { return a+b*a; }
170</pre>
171
172
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]173<h3>Type checking:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]174
175<pre class="code">
176$ <b>clang -fsyntax-only ~/t.c</b>
177</pre>
178
179
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]180<h3>GCC options:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]181
182<pre class="code">
183$ <b>clang -fsyntax-only ~/t.c -pedantic</b>
184/Users/sabre/t.c:2:17: warning: extension used
185typedef float V __attribute__((vector_size(16)));
186 ^
1871 diagnostic generated.
188</pre>
189
190
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]191<h3>Pretty printing from the AST:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]192
193<pre class="code">
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]194$ <b>clang-cc ~/t.c -ast-print</b>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]195typedef float V __attribute__(( vector_size(16) ));
196V foo(V a, V b) {
197 return a + b * a;
198}
199</pre>
200
201
Ted Kremenek35f29c52008-06-17 13:48:36 +0000[diff] [blame]202<h3>Code generation with LLVM:</h3>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]203
204<pre class="code">
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]205$ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llvm-dis</b>
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]206define &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
207entry:
208 %mul = mul &lt;4 x float&gt; %b, %a
209 %add = add &lt;4 x float&gt; %mul, %a
210 ret &lt;4 x float&gt; %add
211}
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]212$ <b>clang-cc ~/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]213..
214_foo:
215 vmaddfp v2, v3, v2, v2
216 blr
Ted Kremenek9b16da32009-03-27 16:32:57 +0000[diff] [blame]217$ <b>clang-cc ~/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]218..
219_foo:
220 mulps %xmm0, %xmm1
221 addps %xmm0, %xmm1
222 movaps %xmm1, %xmm0
223 ret
224</pre>
225
Eric Christopher7dc0e572008-02-08 06:45:49 +0000[diff] [blame]226</div>
227</body>
228</html>