| <!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 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> |
| <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> |
| |
| <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> |
| <li>Standard build process uses CMake. Get it at: |
| <a href="http://www.cmake.org/download"> |
| http://www.cmake.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> |
| <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> |
| <li><tt>cd ../..</tt></li> |
| </ul> |
| </li> |
| <li>Checkout extra Clang Tools: (optional) |
| <ul> |
| <li><tt>cd llvm/tools/clang/tools</tt></li> |
| <li><tt>svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk |
| extra</tt></li> |
| <li><tt>cd ../../../..</tt></li> |
| </ul> |
| </li> |
| <li>Checkout Compiler-RT: |
| <ul> |
| <li><tt>cd llvm/projects</tt></li> |
| <li><tt>svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk |
| compiler-rt</tt></li> |
| <li><tt>cd ../..</tt></li> |
| </ul> |
| </li> |
| <li>Checkout libcxx: (only required to build and run Compiler-RT tests on OS X, optional otherwise) |
| <ul> |
| <li><tt>cd llvm/projects</tt></li> |
| <li><tt>svn co http://llvm.org/svn/llvm-project/libcxx/trunk |
| libcxx</tt></li> |
| <li><tt>cd ../..</tt></li> |
| </ul> |
| </li> |
| <li>Build LLVM and Clang: |
| <ul> |
| <li><tt>mkdir build</tt> (in-tree build is not supported)</li> |
| <li><tt>cd build</tt></li> |
| <li><tt>cmake -G "Unix Makefiles" ../llvm</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 run |
| <tt>make clang</tt>.</li> |
| <li>CMake allows you to generate project files for several IDEs: Xcode, |
| Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), |
| KDevelop3. For more details see |
| <a href="http://llvm.org/docs/CMake.html">Building LLVM with CMake</a> |
| page.</li> |
| <li>You can also build Clang with |
| <a href="http://llvm.org/docs/BuildingLLVMWithAutotools.html"> |
| autotools</a>, but some features may be unavailable there.</li> |
| </ul> |
| </li> |
| |
| <li>If you intend to use Clang's C++ support, you may need to tell it how |
| to find your C++ standard library headers. In general, Clang will detect |
| the best version of libstdc++ headers available and use them - it will |
| look both for system installations of libstdc++ as well as installations |
| adjacent to Clang itself. If your configuration fits neither of these |
| scenarios, you can use the <tt>--with-gcc-toolchain</tt> configure option |
| to tell Clang where the gcc containing the desired libstdc++ is installed. |
| </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.apache.org/packages.html"> |
| http://subversion.apache.org/packages.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 2013 or later</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 2013: <tt>cmake -G "Visual Studio 12" ..\llvm</tt></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 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> |