301 lines
11 KiB
HTML
301 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
|
<title>Clang - Getting Started</title>
|
|
<link type="text/css" rel="stylesheet" href="menu.css" />
|
|
<link type="text/css" rel="stylesheet" href="content.css" />
|
|
</head>
|
|
<body>
|
|
|
|
<!--#include virtual="menu.html.incl"-->
|
|
|
|
<div id="content">
|
|
|
|
<h1>Getting Started: Building and Running Clang</h1>
|
|
|
|
<p>This page gives you the shortest path to checking out Clang and demos a few
|
|
options. This should get you up and running with the minimum of muss and fuss.
|
|
If you like what you see, please consider <a href="get_involved.html">getting
|
|
involved</a> with the Clang community.</p>
|
|
|
|
<h2>A Word of Warning</h2>
|
|
|
|
<p>While this work aims to provide a fully functional C/C++/ObjC front-end, it
|
|
is still relatively new and under heavy development. Currently we believe clang
|
|
to be very usable as a C and Objective-C compiler, however there is no real C++
|
|
support yet (this is obviously a big project). Additionally, for C and
|
|
Objective-C:</p>
|
|
|
|
<ol>
|
|
<li>The semantic analyzer does not produce all of the warnings it should.</li>
|
|
<li>We don't consider the API to be stable yet, and reserve the right to
|
|
change fundamental things.</li>
|
|
<li>Only the X86-32 and X86-64 targets have been well tested.</li>
|
|
</ol>
|
|
|
|
<p>If you run into problems, please file
|
|
bugs in <a href="http://llvm.org/bugs/">LLVM Bugzilla</a> or bring up the issue
|
|
on the
|
|
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang development
|
|
mailing list</a>.</p>
|
|
|
|
<h2 id="build">Building Clang and Working with the Code</h2>
|
|
|
|
<h3 id="buildNix">On Unix-like Systems</h3>
|
|
|
|
<p>If you would like to check out and build Clang, the current procedure is as
|
|
follows:</p>
|
|
|
|
<ol>
|
|
<li>Get the required tools.
|
|
<ul>
|
|
<li>See
|
|
<a href="http://llvm.org/docs/GettingStarted.html#requirements">
|
|
Getting Started with the LLVM System - Requirements</a>.</li>
|
|
<li>Note also that Python is needed for running the test suite.
|
|
Get it at: <a href="http://www.python.org/download">
|
|
http://www.python.org/download</a></li>
|
|
</ul>
|
|
|
|
<li>Checkout LLVM:</li>
|
|
<ul>
|
|
<li>Change directory to where you want the llvm directory placed.</li>
|
|
<li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
|
|
</ul>
|
|
<li>Checkout Clang:</li>
|
|
<ul>
|
|
<li><tt>cd llvm/tools</tt>
|
|
<li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
|
|
</ul>
|
|
<li>Build LLVM and Clang:</li>
|
|
<ul>
|
|
<li><tt>cd ..</tt> (back to llvm)</li>
|
|
<li><tt>./configure</tt></li>
|
|
<li><tt>make</tt></li>
|
|
<li>This builds both LLVM and Clang for debug mode.</li>
|
|
<li>Note: For subsequent Clang development, you can just do make at the
|
|
clang directory level.</li>
|
|
</ul>
|
|
<li>If you intend to work on Clang C++ support, you may need to tell it how
|
|
to find your C++ standard library headers. If Clang cannot find your
|
|
system libstdc++ headers, please follow these instructions:</li>
|
|
<ul>
|
|
<li>'<tt>touch empty.cpp; gcc -v empty.cpp -fsyntax-only</tt>' to get the
|
|
path.</li>
|
|
<li>Look for the comment "FIXME: temporary hack:
|
|
hard-coded paths" in <tt>clang/lib/Frontend/InitHeaderSearch.cpp</tt> and
|
|
change the lines below to include that path.</li>
|
|
</ul>
|
|
<li>Try it out (assuming you add llvm/Debug/bin to your path):</li>
|
|
<ul>
|
|
<li><tt>clang-cc --help</tt></li>
|
|
<li><tt>clang-cc file.c -fsyntax-only</tt> (check for correctness)</li>
|
|
<li><tt>clang-cc file.c -ast-dump</tt> (internal debug dump of ast)</li>
|
|
<li><tt>clang-cc file.c -ast-view</tt> (<a
|
|
href="http://llvm.org/docs/ProgrammersManual.html#ViewGraph">set up graphviz
|
|
and rebuild llvm first</a>)</li>
|
|
<li><tt>clang-cc file.c -emit-llvm</tt> (print out unoptimized llvm code)</li>
|
|
<li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts |
|
|
llvm-dis</tt> (print out optimized llvm code)</li>
|
|
<li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc
|
|
> file.s</tt> (output native machine code)</li>
|
|
</ul>
|
|
<p><em>Note</em>: Here <tt>clang-cc</tt> is the "low-level" frontend
|
|
executable that is similar in purpose to <tt>cc1</tt>. Clang also has a <a
|
|
href="#driver">high-level compiler driver</a> that acts as a drop-in
|
|
replacement for <tt>gcc</tt>.
|
|
</ol>
|
|
|
|
<p>Note that the C front-end uses LLVM, but does not depend on llvm-gcc. If you
|
|
encounter problems with building Clang, make sure you have the latest SVN
|
|
version of LLVM. LLVM contains support libraries for Clang that will be updated
|
|
as well as development on Clang progresses.</p>
|
|
|
|
<h3>Simultaneously Building Clang and LLVM:</h3>
|
|
|
|
<p>Once you have checked out Clang into the llvm source tree it will build along
|
|
with the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at
|
|
once simply run <tt>make</tt> from the root LLVM directory.</p>
|
|
|
|
<p><em>Note:</em> Observe that Clang is technically part of a separate
|
|
Subversion repository. As mentioned above, the latest Clang sources are tied to
|
|
the latest sources in the LLVM tree. You can update your toplevel LLVM project
|
|
and all (possibly unrelated) projects inside it with <tt><b>make
|
|
update</b></tt>. This will run <tt>svn update</tt> on all subdirectories related
|
|
to subversion. </p>
|
|
|
|
<h3 id="buildWindows">Using Visual Studio</h3>
|
|
|
|
<p>The following details setting up for and building Clang on Windows using
|
|
Visual Studio:</p>
|
|
|
|
<ol>
|
|
<li>Get the required tools:</li>
|
|
<ul>
|
|
<li><b>Subversion</b>. Source code control program. Get it from:
|
|
<a href="http://subversion.tigris.org/getting.html">
|
|
http://subversion.tigris.org/getting.html</a></li>
|
|
<li><b>cmake</b>. This is used for generating Visual Studio solution and
|
|
project files. Get it from:
|
|
<a href="http://www.cmake.org/cmake/resources/software.html">
|
|
http://www.cmake.org/cmake/resources/software.html</a></li>
|
|
<li><b>Visual Studio 2005</b>
|
|
(VS 2008 may work also - cmake outputs VS2005 project files)</li>
|
|
<li><b>Python</b>. This is needed only if you will be running the tests
|
|
(which is essential, if you will be developing for clang).
|
|
Get it from:
|
|
<a href="http://www.python.org/download">
|
|
http://www.python.org/download</a></li>
|
|
<li><b>GnuWin32 tools</b>
|
|
These are also necessary for running the tests.
|
|
(Note that the grep from MSYS or Cygwin doesn't work with the tests
|
|
because of embedded double-quotes in the search strings. The GNU
|
|
grep does work in this case.)
|
|
Get them from <a href="http://getgnuwin32.sourceforge.net">
|
|
http://getgnuwin32.sourceforge.net</a>.</li>
|
|
</ul>
|
|
|
|
<li>Checkout LLVM:</li>
|
|
<ul>
|
|
<li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
|
|
</ul>
|
|
<li>Checkout Clang:</li>
|
|
<ul>
|
|
<li><tt>cd llvm\tools</tt>
|
|
<li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li>
|
|
</ul>
|
|
<li>Run cmake to generate the Visual Studio solution and project files:</li>
|
|
<ul>
|
|
<li><tt>cd ..</tt> (Change directory back to the llvm top.)</li>
|
|
<li><tt>cmake .</tt></li>
|
|
<li>The above, if successful, will have created an LLVM.sln file in the
|
|
llvm directory.
|
|
</ul>
|
|
<li>Build Clang:</li>
|
|
<ul>
|
|
<li>Open LLVM.sln in Visual Studio.</li>
|
|
<li>Build the "clang-cc" project for just the compiler front end.
|
|
Alternatively, build the "clang" project for the compiler driver
|
|
(note that the driver is currently broken on Windows),
|
|
or the "ALL_BUILD" project to build everything, including tools.</li>
|
|
</ul>
|
|
<li>Try it out (assuming you added llvm/debug/bin to your path). (See the
|
|
running examples from above.)</li>
|
|
<li>See <a href="hacking.html#testingWindows">
|
|
Hacking on clang - Testing using Visual Studio on Windows</a> for information
|
|
on running regression tests on Windows.</li>
|
|
</ol>
|
|
|
|
<p>Note that once you have checked out both llvm and clang, to synchronize
|
|
to the latest code base, use the <tt>svn update</tt> command in both the
|
|
llvm and llvm\tools\clang directories, as they are separate repositories.</p>
|
|
|
|
<a name="driver"><h2>High-Level Compiler Driver (Drop-in Substitute for GCC)</h2></a>
|
|
|
|
<p>While the <tt>clang-cc</tt> executable is a low-level frontend executable
|
|
that can perform code generation, program analysis, and other actions, it is not
|
|
designed to be a drop-in replacement for GCC's <tt>cc</tt>. For this purpose,
|
|
use the high-level driver, aptly named <tt>clang</tt>. Here are some
|
|
examples of how to use the high-level driver:
|
|
</p>
|
|
|
|
<pre class="code">
|
|
$ <b>cat t.c</b>
|
|
#include <stdio.h>
|
|
int main(int argc, char **argv) { printf("hello world\n"); }
|
|
$ <b>clang t.c</b>
|
|
$ <b>./a.out</b>
|
|
hello world
|
|
</pre>
|
|
|
|
<h2>Examples of using Clang</h2>
|
|
|
|
<p>The high-level driver <tt>clang</tt> is designed to understand most of GCC's
|
|
options, and the lower-level <tt>clang-cc</tt> executable also directly takes
|
|
many of GCC's options. You can see which options <tt>clang-cc</tt> accepts with
|
|
'<tt>clang-cc --help</tt>'. Here are a few examples of using <tt>clang</tt> and
|
|
<tt>clang-cc</tt>:</p>
|
|
|
|
<!-- Thanks to
|
|
http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings
|
|
Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>
|
|
tag. -->
|
|
|
|
<pre class="code">
|
|
$ <b>cat ~/t.c</b>
|
|
typedef float V __attribute__((vector_size(16)));
|
|
V foo(V a, V b) { return a+b*a; }
|
|
</pre>
|
|
|
|
|
|
<h3>Preprocessing:</h3>
|
|
|
|
<pre class="code">
|
|
$ <b>clang ~/t.c -E</b>
|
|
# 1 "/Users/sabre/t.c" 1
|
|
|
|
typedef float V __attribute__((vector_size(16)));
|
|
|
|
V foo(V a, V b) { return a+b*a; }
|
|
</pre>
|
|
|
|
|
|
<h3>Type checking:</h3>
|
|
|
|
<pre class="code">
|
|
$ <b>clang -fsyntax-only ~/t.c</b>
|
|
</pre>
|
|
|
|
|
|
<h3>GCC options:</h3>
|
|
|
|
<pre class="code">
|
|
$ <b>clang -fsyntax-only ~/t.c -pedantic</b>
|
|
/Users/sabre/t.c:2:17: warning: extension used
|
|
typedef float V __attribute__((vector_size(16)));
|
|
^
|
|
1 diagnostic generated.
|
|
</pre>
|
|
|
|
|
|
<h3>Pretty printing from the AST:</h3>
|
|
|
|
<pre class="code">
|
|
$ <b>clang-cc ~/t.c -ast-print</b>
|
|
typedef float V __attribute__(( vector_size(16) ));
|
|
V foo(V a, V b) {
|
|
return a + b * a;
|
|
}
|
|
</pre>
|
|
|
|
|
|
<h3>Code generation with LLVM:</h3>
|
|
|
|
<pre class="code">
|
|
$ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llvm-dis</b>
|
|
define <4 x float> @foo(<4 x float> %a, <4 x float> %b) {
|
|
entry:
|
|
%mul = mul <4 x float> %b, %a
|
|
%add = add <4 x float> %mul, %a
|
|
ret <4 x float> %add
|
|
}
|
|
$ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=ppc32 -mcpu=g5</b>
|
|
..
|
|
_foo:
|
|
vmaddfp v2, v3, v2, v2
|
|
blr
|
|
$ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=x86 -mcpu=yonah</b>
|
|
..
|
|
_foo:
|
|
mulps %xmm0, %xmm1
|
|
addps %xmm0, %xmm1
|
|
movaps %xmm1, %xmm0
|
|
ret
|
|
</pre>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|