1*f4a2713aSLionel Sambuc<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2*f4a2713aSLionel Sambuc "http://www.w3.org/TR/html4/strict.dtd"> 3*f4a2713aSLionel Sambuc<html> 4*f4a2713aSLionel Sambuc<head> 5*f4a2713aSLionel Sambuc <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 6*f4a2713aSLionel Sambuc <title>Clang - Getting Started</title> 7*f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="menu.css"> 8*f4a2713aSLionel Sambuc <link type="text/css" rel="stylesheet" href="content.css"> 9*f4a2713aSLionel Sambuc</head> 10*f4a2713aSLionel Sambuc<body> 11*f4a2713aSLionel Sambuc 12*f4a2713aSLionel Sambuc<!--#include virtual="menu.html.incl"--> 13*f4a2713aSLionel Sambuc 14*f4a2713aSLionel Sambuc<div id="content"> 15*f4a2713aSLionel Sambuc 16*f4a2713aSLionel Sambuc<h1>Getting Started: Building and Running Clang</h1> 17*f4a2713aSLionel Sambuc 18*f4a2713aSLionel Sambuc<p>This page gives you the shortest path to checking out Clang and demos a few 19*f4a2713aSLionel Sambucoptions. This should get you up and running with the minimum of muss and fuss. 20*f4a2713aSLionel SambucIf you like what you see, please consider <a href="get_involved.html">getting 21*f4a2713aSLionel Sambucinvolved</a> with the Clang community. If you run into problems, please file 22*f4a2713aSLionel Sambucbugs in <a href="http://llvm.org/bugs/">LLVM Bugzilla</a>.</p> 23*f4a2713aSLionel Sambuc 24*f4a2713aSLionel Sambuc<h2 id="download">Release Clang Versions</h2> 25*f4a2713aSLionel Sambuc 26*f4a2713aSLionel Sambuc<p>Clang has been released as part of regular LLVM releases since LLVM 2.6. You 27*f4a2713aSLionel Sambuccan download the release versions 28*f4a2713aSLionel Sambucfrom <a href="http://llvm.org/releases/">http://llvm.org/releases/</a>.</p> 29*f4a2713aSLionel Sambuc 30*f4a2713aSLionel Sambuc<h2 id="build">Building Clang and Working with the Code</h2> 31*f4a2713aSLionel Sambuc 32*f4a2713aSLionel Sambuc<h3 id="buildNix">On Unix-like Systems</h3> 33*f4a2713aSLionel Sambuc 34*f4a2713aSLionel Sambuc<p>If you would like to check out and build Clang, the current procedure is as 35*f4a2713aSLionel Sambucfollows:</p> 36*f4a2713aSLionel Sambuc 37*f4a2713aSLionel Sambuc<ol> 38*f4a2713aSLionel Sambuc <li>Get the required tools. 39*f4a2713aSLionel Sambuc <ul> 40*f4a2713aSLionel Sambuc <li>See 41*f4a2713aSLionel Sambuc <a href="http://llvm.org/docs/GettingStarted.html#requirements"> 42*f4a2713aSLionel Sambuc Getting Started with the LLVM System - Requirements</a>.</li> 43*f4a2713aSLionel Sambuc <li>Note also that Python is needed for running the test suite. 44*f4a2713aSLionel Sambuc Get it at: <a href="http://www.python.org/download"> 45*f4a2713aSLionel Sambuc http://www.python.org/download</a></li> 46*f4a2713aSLionel Sambuc </ul> 47*f4a2713aSLionel Sambuc 48*f4a2713aSLionel Sambuc <li>Checkout LLVM: 49*f4a2713aSLionel Sambuc <ul> 50*f4a2713aSLionel Sambuc <li>Change directory to where you want the llvm directory placed.</li> 51*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> 52*f4a2713aSLionel Sambuc </ul> 53*f4a2713aSLionel Sambuc </li> 54*f4a2713aSLionel Sambuc <li>Checkout Clang: 55*f4a2713aSLionel Sambuc <ul> 56*f4a2713aSLionel Sambuc <li><tt>cd llvm/tools</tt></li> 57*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> 58*f4a2713aSLionel Sambuc <li><tt>cd ../..</tt></li> 59*f4a2713aSLionel Sambuc </ul> 60*f4a2713aSLionel Sambuc </li> 61*f4a2713aSLionel Sambuc <li>Checkout extra Clang Tools: (optional) 62*f4a2713aSLionel Sambuc <ul> 63*f4a2713aSLionel Sambuc <li><tt>cd llvm/tools/clang/tools</tt></li> 64*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk 65*f4a2713aSLionel Sambuc extra</tt></li> 66*f4a2713aSLionel Sambuc <li><tt>cd ../../../..</tt></li> 67*f4a2713aSLionel Sambuc </ul> 68*f4a2713aSLionel Sambuc </li> 69*f4a2713aSLionel Sambuc <li>Checkout Compiler-RT: 70*f4a2713aSLionel Sambuc <ul> 71*f4a2713aSLionel Sambuc <li><tt>cd llvm/projects</tt></li> 72*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk 73*f4a2713aSLionel Sambuc compiler-rt</tt></li> 74*f4a2713aSLionel Sambuc <li><tt>cd ../..</tt></li> 75*f4a2713aSLionel Sambuc </ul> 76*f4a2713aSLionel Sambuc </li> 77*f4a2713aSLionel Sambuc <li>Build LLVM and Clang: 78*f4a2713aSLionel Sambuc <ul> 79*f4a2713aSLionel Sambuc <li><tt>mkdir build</tt> (for building without polluting the source dir) 80*f4a2713aSLionel Sambuc </li> 81*f4a2713aSLionel Sambuc <li><tt>cd build</tt></li> 82*f4a2713aSLionel Sambuc <li><tt>../llvm/configure</tt></li> 83*f4a2713aSLionel Sambuc <li><tt>make</tt></li> 84*f4a2713aSLionel Sambuc <li>This builds both LLVM and Clang for debug mode.</li> 85*f4a2713aSLionel Sambuc <li>Note: For subsequent Clang development, you can just do make at the 86*f4a2713aSLionel Sambuc clang directory level.</li> 87*f4a2713aSLionel Sambuc <li>It is also possible to use CMake instead of the makefiles. With CMake 88*f4a2713aSLionel Sambuc it is possible to generate project files for several IDEs: Xcode, Eclipse 89*f4a2713aSLionel Sambuc CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.</li> 90*f4a2713aSLionel Sambuc </ul> 91*f4a2713aSLionel Sambuc </li> 92*f4a2713aSLionel Sambuc 93*f4a2713aSLionel Sambuc <li>If you intend to use Clang's C++ support, you may need to tell it how 94*f4a2713aSLionel Sambuc to find your C++ standard library headers. In general, Clang will detect 95*f4a2713aSLionel Sambuc the best version of libstdc++ headers available and use them - it will 96*f4a2713aSLionel Sambuc look both for system installations of libstdc++ as well as installations 97*f4a2713aSLionel Sambuc adjacent to Clang itself. If your configuration fits neither of these 98*f4a2713aSLionel Sambuc scenarios, you can use the <tt>--with-gcc-toolchain</tt> configure option 99*f4a2713aSLionel Sambuc to tell Clang where the gcc containing the desired libstdc++ is installed. 100*f4a2713aSLionel Sambuc </li> 101*f4a2713aSLionel Sambuc <li>Try it out (assuming you add llvm/Debug+Asserts/bin to your path): 102*f4a2713aSLionel Sambuc <ul> 103*f4a2713aSLionel Sambuc <li><tt>clang --help</tt></li> 104*f4a2713aSLionel Sambuc <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li> 105*f4a2713aSLionel Sambuc <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li> 106*f4a2713aSLionel Sambuc <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li> 107*f4a2713aSLionel Sambuc <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li> 108*f4a2713aSLionel Sambuc </ul> 109*f4a2713aSLionel Sambuc </li> 110*f4a2713aSLionel Sambuc</ol> 111*f4a2713aSLionel Sambuc 112*f4a2713aSLionel Sambuc<p>Note that the C front-end uses LLVM, but does not depend on llvm-gcc. If you 113*f4a2713aSLionel Sambucencounter problems with building Clang, make sure you have the latest SVN 114*f4a2713aSLionel Sambucversion of LLVM. LLVM contains support libraries for Clang that will be updated 115*f4a2713aSLionel Sambucas well as development on Clang progresses.</p> 116*f4a2713aSLionel Sambuc 117*f4a2713aSLionel Sambuc<h3>Simultaneously Building Clang and LLVM:</h3> 118*f4a2713aSLionel Sambuc 119*f4a2713aSLionel Sambuc<p>Once you have checked out Clang into the llvm source tree it will build along 120*f4a2713aSLionel Sambucwith the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at 121*f4a2713aSLionel Sambuconce simply run <tt>make</tt> from the root LLVM directory.</p> 122*f4a2713aSLionel Sambuc 123*f4a2713aSLionel Sambuc<p><em>Note:</em> Observe that Clang is technically part of a separate 124*f4a2713aSLionel SambucSubversion repository. As mentioned above, the latest Clang sources are tied to 125*f4a2713aSLionel Sambucthe latest sources in the LLVM tree. You can update your toplevel LLVM project 126*f4a2713aSLionel Sambucand all (possibly unrelated) projects inside it with <tt><b>make 127*f4a2713aSLionel Sambucupdate</b></tt>. This will run <tt>svn update</tt> on all subdirectories related 128*f4a2713aSLionel Sambucto subversion. </p> 129*f4a2713aSLionel Sambuc 130*f4a2713aSLionel Sambuc<h3 id="buildWindows">Using Visual Studio</h3> 131*f4a2713aSLionel Sambuc 132*f4a2713aSLionel Sambuc<p>The following details setting up for and building Clang on Windows using 133*f4a2713aSLionel SambucVisual Studio:</p> 134*f4a2713aSLionel Sambuc 135*f4a2713aSLionel Sambuc<ol> 136*f4a2713aSLionel Sambuc <li>Get the required tools: 137*f4a2713aSLionel Sambuc <ul> 138*f4a2713aSLionel Sambuc <li><b>Subversion</b>. Source code control program. Get it from: 139*f4a2713aSLionel Sambuc <a href="http://subversion.tigris.org/getting.html"> 140*f4a2713aSLionel Sambuc http://subversion.tigris.org/getting.html</a></li> 141*f4a2713aSLionel Sambuc <li><b>CMake</b>. This is used for generating Visual Studio solution and 142*f4a2713aSLionel Sambuc project files. Get it from: 143*f4a2713aSLionel Sambuc <a href="http://www.cmake.org/cmake/resources/software.html"> 144*f4a2713aSLionel Sambuc http://www.cmake.org/cmake/resources/software.html</a></li> 145*f4a2713aSLionel Sambuc <li><b>Visual Studio 2008 or 2010</b></li> 146*f4a2713aSLionel Sambuc <li><b>Python</b>. This is needed only if you will be running the tests 147*f4a2713aSLionel Sambuc (which is essential, if you will be developing for clang). 148*f4a2713aSLionel Sambuc Get it from: 149*f4a2713aSLionel Sambuc <a href="http://www.python.org/download/"> 150*f4a2713aSLionel Sambuc http://www.python.org/download/</a></li> 151*f4a2713aSLionel Sambuc <li><b>GnuWin32 tools</b> 152*f4a2713aSLionel Sambuc These are also necessary for running the tests. 153*f4a2713aSLionel Sambuc (Note that the grep from MSYS or Cygwin doesn't work with the tests 154*f4a2713aSLionel Sambuc because of embedded double-quotes in the search strings. The GNU 155*f4a2713aSLionel Sambuc grep does work in this case.) 156*f4a2713aSLionel Sambuc Get them from <a href="http://getgnuwin32.sourceforge.net/"> 157*f4a2713aSLionel Sambuc http://getgnuwin32.sourceforge.net/</a>.</li> 158*f4a2713aSLionel Sambuc </ul> 159*f4a2713aSLionel Sambuc </li> 160*f4a2713aSLionel Sambuc 161*f4a2713aSLionel Sambuc <li>Checkout LLVM: 162*f4a2713aSLionel Sambuc <ul> 163*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> 164*f4a2713aSLionel Sambuc </ul> 165*f4a2713aSLionel Sambuc </li> 166*f4a2713aSLionel Sambuc <li>Checkout Clang: 167*f4a2713aSLionel Sambuc <ul> 168*f4a2713aSLionel Sambuc <li><tt>cd llvm\tools</tt> 169*f4a2713aSLionel Sambuc <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> 170*f4a2713aSLionel Sambuc </ul> 171*f4a2713aSLionel Sambuc </li> 172*f4a2713aSLionel Sambuc <li>Run CMake to generate the Visual Studio solution and project files: 173*f4a2713aSLionel Sambuc <ul> 174*f4a2713aSLionel Sambuc <li><tt>cd ..\..</tt> (back to where you started)</li> 175*f4a2713aSLionel Sambuc <li><tt>mkdir build</tt> (for building without polluting the source dir)</li> 176*f4a2713aSLionel Sambuc <li><tt>cd build</tt></li> 177*f4a2713aSLionel Sambuc <li>If you are using Visual Studio 2008: <tt>cmake -G "Visual Studio 9 2008" ..\llvm</tt></li> 178*f4a2713aSLionel Sambuc <li>Or if you are using Visual Studio 2010: <tt>cmake -G "Visual Studio 10" ..\llvm</tt></li> 179*f4a2713aSLionel Sambuc <li>See the <a href="http://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for 180*f4a2713aSLionel Sambuc more information on other configuration options for CMake.</li> 181*f4a2713aSLionel Sambuc <li>The above, if successful, will have created an LLVM.sln file in the 182*f4a2713aSLionel Sambuc <tt>build</tt> directory. 183*f4a2713aSLionel Sambuc </ul> 184*f4a2713aSLionel Sambuc </li> 185*f4a2713aSLionel Sambuc <li>Build Clang: 186*f4a2713aSLionel Sambuc <ul> 187*f4a2713aSLionel Sambuc <li>Open LLVM.sln in Visual Studio.</li> 188*f4a2713aSLionel Sambuc <li>Build the "clang" project for just the compiler driver and front end, or 189*f4a2713aSLionel Sambuc the "ALL_BUILD" project to build everything, including tools.</li> 190*f4a2713aSLionel Sambuc </ul> 191*f4a2713aSLionel Sambuc </li> 192*f4a2713aSLionel Sambuc <li>Try it out (assuming you added llvm/debug/bin to your path). (See the 193*f4a2713aSLionel Sambuc running examples from above.)</li> 194*f4a2713aSLionel Sambuc <li>See <a href="hacking.html#testingWindows"> 195*f4a2713aSLionel Sambuc Hacking on clang - Testing using Visual Studio on Windows</a> for information 196*f4a2713aSLionel Sambuc on running regression tests on Windows.</li> 197*f4a2713aSLionel Sambuc</ol> 198*f4a2713aSLionel Sambuc 199*f4a2713aSLionel Sambuc<p>Note that once you have checked out both llvm and clang, to synchronize 200*f4a2713aSLionel Sambucto the latest code base, use the <tt>svn update</tt> command in both the 201*f4a2713aSLionel Sambucllvm and llvm\tools\clang directories, as they are separate repositories.</p> 202*f4a2713aSLionel Sambuc 203*f4a2713aSLionel Sambuc<h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2> 204*f4a2713aSLionel Sambuc 205*f4a2713aSLionel Sambuc<p>The <tt>clang</tt> tool is the compiler driver and front-end, which is 206*f4a2713aSLionel Sambucdesigned to be a drop-in replacement for the <tt>gcc</tt> command. Here are 207*f4a2713aSLionel Sambucsome examples of how to use the high-level driver: 208*f4a2713aSLionel Sambuc</p> 209*f4a2713aSLionel Sambuc 210*f4a2713aSLionel Sambuc<pre class="code"> 211*f4a2713aSLionel Sambuc$ <b>cat t.c</b> 212*f4a2713aSLionel Sambuc#include <stdio.h> 213*f4a2713aSLionel Sambucint main(int argc, char **argv) { printf("hello world\n"); } 214*f4a2713aSLionel Sambuc$ <b>clang t.c</b> 215*f4a2713aSLionel Sambuc$ <b>./a.out</b> 216*f4a2713aSLionel Sambuchello world 217*f4a2713aSLionel Sambuc</pre> 218*f4a2713aSLionel Sambuc 219*f4a2713aSLionel Sambuc<p>The 'clang' driver is designed to work as closely to GCC as possible to 220*f4a2713aSLionel Sambuc maximize portability. The only major difference between the two is that 221*f4a2713aSLionel Sambuc Clang defaults to gnu99 mode while GCC defaults to gnu89 mode. If you see 222*f4a2713aSLionel Sambuc weird link-time errors relating to inline functions, try passing -std=gnu89 223*f4a2713aSLionel Sambuc to clang.</p> 224*f4a2713aSLionel Sambuc 225*f4a2713aSLionel Sambuc<h2>Examples of using Clang</h2> 226*f4a2713aSLionel Sambuc 227*f4a2713aSLionel Sambuc<!-- Thanks to 228*f4a2713aSLionel Sambuc http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings 229*f4a2713aSLionel SambucSite suggested using pre in CSS, but doesn't work in IE, so went for the <pre> 230*f4a2713aSLionel Sambuctag. --> 231*f4a2713aSLionel Sambuc 232*f4a2713aSLionel Sambuc<pre class="code"> 233*f4a2713aSLionel Sambuc$ <b>cat ~/t.c</b> 234*f4a2713aSLionel Sambuctypedef float V __attribute__((vector_size(16))); 235*f4a2713aSLionel SambucV foo(V a, V b) { return a+b*a; } 236*f4a2713aSLionel Sambuc</pre> 237*f4a2713aSLionel Sambuc 238*f4a2713aSLionel Sambuc 239*f4a2713aSLionel Sambuc<h3>Preprocessing:</h3> 240*f4a2713aSLionel Sambuc 241*f4a2713aSLionel Sambuc<pre class="code"> 242*f4a2713aSLionel Sambuc$ <b>clang ~/t.c -E</b> 243*f4a2713aSLionel Sambuc# 1 "/Users/sabre/t.c" 1 244*f4a2713aSLionel Sambuc 245*f4a2713aSLionel Sambuctypedef float V __attribute__((vector_size(16))); 246*f4a2713aSLionel Sambuc 247*f4a2713aSLionel SambucV foo(V a, V b) { return a+b*a; } 248*f4a2713aSLionel Sambuc</pre> 249*f4a2713aSLionel Sambuc 250*f4a2713aSLionel Sambuc 251*f4a2713aSLionel Sambuc<h3>Type checking:</h3> 252*f4a2713aSLionel Sambuc 253*f4a2713aSLionel Sambuc<pre class="code"> 254*f4a2713aSLionel Sambuc$ <b>clang -fsyntax-only ~/t.c</b> 255*f4a2713aSLionel Sambuc</pre> 256*f4a2713aSLionel Sambuc 257*f4a2713aSLionel Sambuc 258*f4a2713aSLionel Sambuc<h3>GCC options:</h3> 259*f4a2713aSLionel Sambuc 260*f4a2713aSLionel Sambuc<pre class="code"> 261*f4a2713aSLionel Sambuc$ <b>clang -fsyntax-only ~/t.c -pedantic</b> 262*f4a2713aSLionel Sambuc/Users/sabre/t.c:2:17: <span style="color:magenta">warning:</span> extension used 263*f4a2713aSLionel Sambuc<span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span> 264*f4a2713aSLionel Sambuc<span style="color:blue"> ^</span> 265*f4a2713aSLionel Sambuc1 diagnostic generated. 266*f4a2713aSLionel Sambuc</pre> 267*f4a2713aSLionel Sambuc 268*f4a2713aSLionel Sambuc 269*f4a2713aSLionel Sambuc<h3>Pretty printing from the AST:</h3> 270*f4a2713aSLionel Sambuc 271*f4a2713aSLionel Sambuc<p>Note, the <tt>-cc1</tt> argument indicates the compiler front-end, and 272*f4a2713aSLionel Sambucnot the driver, should be run. The compiler front-end has several additional 273*f4a2713aSLionel SambucClang specific features which are not exposed through the GCC compatible driver 274*f4a2713aSLionel Sambucinterface.</p> 275*f4a2713aSLionel Sambuc 276*f4a2713aSLionel Sambuc<pre class="code"> 277*f4a2713aSLionel Sambuc$ <b>clang -cc1 ~/t.c -ast-print</b> 278*f4a2713aSLionel Sambuctypedef float V __attribute__(( vector_size(16) )); 279*f4a2713aSLionel SambucV foo(V a, V b) { 280*f4a2713aSLionel Sambuc return a + b * a; 281*f4a2713aSLionel Sambuc} 282*f4a2713aSLionel Sambuc</pre> 283*f4a2713aSLionel Sambuc 284*f4a2713aSLionel Sambuc 285*f4a2713aSLionel Sambuc<h3>Code generation with LLVM:</h3> 286*f4a2713aSLionel Sambuc 287*f4a2713aSLionel Sambuc<pre class="code"> 288*f4a2713aSLionel Sambuc$ <b>clang ~/t.c -S -emit-llvm -o -</b> 289*f4a2713aSLionel Sambucdefine <4 x float> @foo(<4 x float> %a, <4 x float> %b) { 290*f4a2713aSLionel Sambucentry: 291*f4a2713aSLionel Sambuc %mul = mul <4 x float> %b, %a 292*f4a2713aSLionel Sambuc %add = add <4 x float> %mul, %a 293*f4a2713aSLionel Sambuc ret <4 x float> %add 294*f4a2713aSLionel Sambuc} 295*f4a2713aSLionel Sambuc$ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i> 296*f4a2713aSLionel Sambuc... 297*f4a2713aSLionel Sambuc_foo: 298*f4a2713aSLionel SambucLeh_func_begin1: 299*f4a2713aSLionel Sambuc mulps %xmm0, %xmm1 300*f4a2713aSLionel Sambuc addps %xmm1, %xmm0 301*f4a2713aSLionel Sambuc ret 302*f4a2713aSLionel SambucLeh_func_end1: 303*f4a2713aSLionel Sambuc</pre> 304*f4a2713aSLionel Sambuc 305*f4a2713aSLionel Sambuc</div> 306*f4a2713aSLionel Sambuc</body> 307*f4a2713aSLionel Sambuc</html> 308