diff options
Diffstat (limited to 'www/get_started.html')
| -rw-r--r-- | www/get_started.html | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/www/get_started.html b/www/get_started.html new file mode 100644 index 0000000..437cb38 --- /dev/null +++ b/www/get_started.html @@ -0,0 +1,228 @@ +<!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> + +<p>If you would like to check out and build Clang, the current procedure is as +follows:</p> + +<ol> + <li><a href="http://www.llvm.org/docs/GettingStarted.html#checkout">Checkout + and build LLVM</a> from SVN head:</li> + + <ul> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> + <li><tt>cd llvm</tt></li> + <li><tt>./configure; make</tt></li> + </ul> + <li>Checkout Clang:</li> + <ul> + <li>From within the <tt>llvm</tt> directory (where you + built llvm):</li> + <li><tt>cd tools</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></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>Build Clang:</li> + <ul> + <li><tt>cd clang</tt> (assuming that you are in <tt>llvm/tools</tt>)</li> + <li><tt>make</tt> (this will give you a debug build)</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> + +<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> |
