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