diff options
Diffstat (limited to 'clang/www/get_started.html')
| -rw-r--r-- | clang/www/get_started.html | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/clang/www/get_started.html b/clang/www/get_started.html new file mode 100644 index 0000000..d819532 --- /dev/null +++ b/clang/www/get_started.html @@ -0,0 +1,306 @@ +<!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. If you run into problems, please file +bugs in <a href="http://llvm.org/bugs/">LLVM Bugzilla</a>.</p> + +<h2 id="download">Release Clang Versions</h2> + +<p>Clang has been released as part of regular LLVM releases since LLVM 2.6. You +can download the release versions +from <a href="http://llvm.org/releases/">http://llvm.org/releases/</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: + <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> + <li>Checkout Clang: + <ul> + <li><tt>cd llvm/tools</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> + </ul> + </li> + <li>Checkout Compiler-RT: + <ul> + <li><tt>cd ../..</tt> (back to where you started)</li> + <li><tt>cd llvm/projects</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk + compiler-rt</tt></li> + </ul> + </li> + <li>Build LLVM and Clang: + <ul> + <li><tt>cd ../..</tt> (back to where you started)</li> + <li><tt>mkdir build</tt> (for building without polluting the source dir) + </li> + <li><tt>cd build</tt></li> + <li><tt>../llvm/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> + <li>It is also possible to use CMake instead of the makefiles. With CMake + it is also possible to generate project files for several IDEs: Eclipse + CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.</li> + </ul> + </li> + + <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: + <ul> + <li>'<tt>gcc -v -x c++ /dev/null -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> + <li>Try it out (assuming you add llvm/Debug+Asserts/bin to your path): + <ul> + <li><tt>clang --help</tt></li> + <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li> + <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li> + <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li> + <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li> + </ul> + </li> +</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: + <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 2008 or 2010</b></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> + + <li>Checkout LLVM: + <ul> + <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> + </ul> + </li> + <li>Checkout Clang: + <ul> + <li><tt>cd llvm\tools</tt> + <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> + </ul> + </li> + <li>Run cmake to generate the Visual Studio solution and project files: + <ul> + <li><tt>cd ..\..</tt> (back to where you started)</li> + <li><tt>mkdir build</tt> (for building without polluting the source dir)</li> + <li><tt>cd build</tt></li> + <li>If you are using Visual Studio 2008: <tt>cmake -G "Visual Studio 9 2008" ..\llvm</tt></li> + <li>Or if you are using Visual Studio 2010: <tt>cmake -G "Visual Studio 10" ..\llvm</tt></li> + <li>By default, cmake will target LLVM to X86. If you want all targets + (needed if you want to run the LLVM tests), add the <tt>-DLLVM_TARGETS_TO_BUILD=all</tt> option to the + cmake command line. Or specify a target from the LLVM_TARGETS_TO_BUILD + definition in CMakeLists.txt.</li> + <li>See the <a href="http://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for + more information on other configuration options for cmake.</li> + <li>The above, if successful, will have created an LLVM.sln file in the + <tt>build</tt> directory. + </ul> + </li> + <li>Build Clang: + <ul> + <li>Open LLVM.sln in Visual Studio.</li> + <li>Build the "clang" project for just the compiler driver and front end, or + the "ALL_BUILD" project to build everything, including tools.</li> + </ul> + </li> + <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> + +<h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2> + +<p>The <tt>clang</tt> tool is the compiler driver and front-end, which is +designed to be a drop-in replacement for the <tt>gcc</tt> command. 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> + +<p>The 'clang' driver is designed to work as closely to GCC as possible to + maximize portability. The only major difference between the two is that + Clang defaults to gnu99 mode while GCC defaults to gnu89 mode. If you see + weird link-time errors relating to inline functions, try passing -std=gnu89 + to clang.</p> + +<h2>Examples of using Clang</h2> + +<!-- 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: <span style="color:magenta">warning:</span> extension used +<span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span> +<span style="color:blue"> ^</span> +1 diagnostic generated. +</pre> + + +<h3>Pretty printing from the AST:</h3> + +<p>Note, the <tt>-cc1</tt> argument indicates the the compiler front-end, and +not the driver, should be run. The compiler front-end has several additional +Clang specific features which are not exposed through the GCC compatible driver +interface.</p> + +<pre class="code"> +$ <b>clang -cc1 ~/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 ~/t.c -S -emit-llvm -o -</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 -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i> +... +_foo: +Leh_func_begin1: + mulps %xmm0, %xmm1 + addps %xmm1, %xmm0 + ret +Leh_func_end1: +</pre> + +</div> +</body> +</html> |