1e5dd7070Spatrick<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2e5dd7070Spatrick "http://www.w3.org/TR/html4/strict.dtd"> 3e5dd7070Spatrick<html> 4e5dd7070Spatrick<head> 5e5dd7070Spatrick <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 6e5dd7070Spatrick <title>Clang - Getting Started</title> 7e5dd7070Spatrick <link type="text/css" rel="stylesheet" href="menu.css"> 8e5dd7070Spatrick <link type="text/css" rel="stylesheet" href="content.css"> 9e5dd7070Spatrick</head> 10e5dd7070Spatrick<body> 11e5dd7070Spatrick 12e5dd7070Spatrick<!--#include virtual="menu.html.incl"--> 13e5dd7070Spatrick 14e5dd7070Spatrick<div id="content"> 15e5dd7070Spatrick 16e5dd7070Spatrick<h1>Getting Started: Building and Running Clang</h1> 17e5dd7070Spatrick 18e5dd7070Spatrick<p>This page gives you the shortest path to checking out Clang and demos a few 19e5dd7070Spatrickoptions. This should get you up and running with the minimum of muss and fuss. 20e5dd7070SpatrickIf you like what you see, please consider <a href="get_involved.html">getting 21e5dd7070Spatrickinvolved</a> with the Clang community. If you run into problems, please file 22*12c85518Srobertbugs on <a href="https://github.com/llvm/llvm-project/issues">the LLVM bug tracker</a>.</p> 23e5dd7070Spatrick 24e5dd7070Spatrick<h2 id="download">Release Clang Versions</h2> 25e5dd7070Spatrick 26e5dd7070Spatrick<p>Clang is released as part of regular LLVM releases. You can download the release versions from <a href="https://llvm.org/releases/">https://llvm.org/releases/</a>.</p> 27e5dd7070Spatrick<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> 28e5dd7070Spatrick 29e5dd7070Spatrick<h2 id="build">Building Clang and Working with the Code</h2> 30e5dd7070Spatrick 31e5dd7070Spatrick<h3 id="buildNix">On Unix-like Systems</h3> 32e5dd7070Spatrick 33e5dd7070Spatrick<p>If you would like to check out and build Clang, the current procedure is as 34e5dd7070Spatrickfollows:</p> 35e5dd7070Spatrick 36e5dd7070Spatrick<ol> 37e5dd7070Spatrick <li>Get the required tools. 38e5dd7070Spatrick <ul> 39e5dd7070Spatrick <li>See 40e5dd7070Spatrick <a href="https://llvm.org/docs/GettingStarted.html#requirements"> 41e5dd7070Spatrick Getting Started with the LLVM System - Requirements</a>.</li> 42e5dd7070Spatrick <li>Note also that Python is needed for running the test suite. 43e5dd7070Spatrick Get it at: <a href="https://www.python.org/downloads/"> 44e5dd7070Spatrick https://www.python.org/downloads/</a></li> 45e5dd7070Spatrick <li>Standard build process uses CMake. Get it at: 46e5dd7070Spatrick <a href="https://cmake.org/download/"> 47e5dd7070Spatrick https://cmake.org/download/</a></li> 48e5dd7070Spatrick </ul> 49e5dd7070Spatrick 50e5dd7070Spatrick <li>Check out the LLVM project: 51e5dd7070Spatrick <ul> 52e5dd7070Spatrick <li>Change directory to where you want the llvm directory placed.</li> 53e5dd7070Spatrick <li><tt>git clone https://github.com/llvm/llvm-project.git</tt></li> 54a9ac8606Spatrick <li>The above command is very slow. It can be made faster by creating a shallow clone. Shallow clone saves storage and speeds up the checkout time. This is done by using the command: 55a9ac8606Spatrick <ul> 56a9ac8606Spatrick <li><tt>git clone --depth=1 https://github.com/llvm/llvm-project.git (using this only the latest version of llvm can be built)</tt></li> 57a9ac8606Spatrick <li>For normal users looking to just compile, this command works fine. But if someone later becomes a contributor, since they can't push code from a shallow clone, it needs to be converted into a full clone: 58a9ac8606Spatrick <ul> 59a9ac8606Spatrick <li><tt>cd llvm-project</tt></li> 60a9ac8606Spatrick <li><tt>git fetch --unshallow</tt></li> 61a9ac8606Spatrick </ul> 62a9ac8606Spatrick </li> 63a9ac8606Spatrick </ul> 64a9ac8606Spatrick </li> 65e5dd7070Spatrick </ul> 66e5dd7070Spatrick </li> 67e5dd7070Spatrick <li>Build LLVM and Clang: 68e5dd7070Spatrick <ul> 69e5dd7070Spatrick <li><tt>cd llvm-project</tt></li> 70e5dd7070Spatrick <li><tt>mkdir build</tt> (in-tree build is not supported)</li> 71e5dd7070Spatrick <li><tt>cd build</tt></li> 72*12c85518Srobert <li>This builds both LLVM and Clang in release mode. Alternatively, if 73*12c85518Srobert you need a debug build, switch Release to Debug. See 74*12c85518Srobert <a href="https://llvm.org/docs/CMake.html#frequently-used-cmake-variables">frequently used cmake variables</a> 75*12c85518Srobert for more options. 76*12c85518Srobert </li> 77*12c85518Srobert <li><tt>cmake -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" ../llvm</tt></li> 78e5dd7070Spatrick <li><tt>make</tt></li> 79e5dd7070Spatrick <li>Note: For subsequent Clang development, you can just run 80e5dd7070Spatrick <tt>make clang</tt>.</li> 81e5dd7070Spatrick <li>CMake allows you to generate project files for several IDEs: Xcode, 82e5dd7070Spatrick Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator), 83e5dd7070Spatrick KDevelop3. For more details see 84e5dd7070Spatrick <a href="https://llvm.org/docs/CMake.html">Building LLVM with CMake</a> 85e5dd7070Spatrick page.</li> 86e5dd7070Spatrick </ul> 87e5dd7070Spatrick </li> 88e5dd7070Spatrick 89e5dd7070Spatrick <li>If you intend to use Clang's C++ support, you may need to tell it how 90e5dd7070Spatrick to find your C++ standard library headers. In general, Clang will detect 91e5dd7070Spatrick the best version of libstdc++ headers available and use them - it will 92e5dd7070Spatrick look both for system installations of libstdc++ as well as installations 93e5dd7070Spatrick adjacent to Clang itself. If your configuration fits neither of these 94e5dd7070Spatrick scenarios, you can use the <tt>-DGCC_INSTALL_PREFIX</tt> cmake option 95e5dd7070Spatrick to tell Clang where the gcc containing the desired libstdc++ is installed. 96e5dd7070Spatrick </li> 97e5dd7070Spatrick <li>Try it out (assuming you add llvm/build/bin to your path): 98e5dd7070Spatrick <ul> 99e5dd7070Spatrick <li><tt>clang --help</tt></li> 100e5dd7070Spatrick <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li> 101e5dd7070Spatrick <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li> 102e5dd7070Spatrick <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li> 103e5dd7070Spatrick <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li> 104e5dd7070Spatrick </ul> 105e5dd7070Spatrick </li> 106e5dd7070Spatrick <li>Run the testsuite: 107e5dd7070Spatrick <ul> 108e5dd7070Spatrick <li><tt>make check-clang</tt></li> 109e5dd7070Spatrick </ul> 110e5dd7070Spatrick </li> 111e5dd7070Spatrick</ol> 112e5dd7070Spatrick 113e5dd7070Spatrick<h3 id="buildWindows">Using Visual Studio</h3> 114e5dd7070Spatrick 115e5dd7070Spatrick<p>The following details setting up for and building Clang on Windows using 116e5dd7070SpatrickVisual Studio:</p> 117e5dd7070Spatrick 118e5dd7070Spatrick<ol> 119e5dd7070Spatrick <li>Get the required tools: 120e5dd7070Spatrick <ul> 121e5dd7070Spatrick <li><b>Git</b>. Source code control program. Get it from: 122e5dd7070Spatrick <a href="https://git-scm.com/download"> 123e5dd7070Spatrick https://git-scm.com/download</a></li> 124e5dd7070Spatrick <li><b>CMake</b>. This is used for generating Visual Studio solution and 125e5dd7070Spatrick project files. Get it from: 126e5dd7070Spatrick <a href="https://cmake.org/download/"> 127e5dd7070Spatrick https://cmake.org/download/</a></li> 128e5dd7070Spatrick <li><b>Visual Studio 2017 or later</b></li> 129e5dd7070Spatrick <li><b>Python</b>. It is used to run the clang test suite. Get it from: 130e5dd7070Spatrick <a href="https://www.python.org/download/"> 131e5dd7070Spatrick https://www.python.org/download/</a></li> 132e5dd7070Spatrick <li><b>GnuWin32 tools</b> 133e5dd7070Spatrick The Clang and LLVM test suite use various GNU core utilities, such as 134e5dd7070Spatrick <tt>grep</tt>, <tt>sed</tt>, and <tt>find</tt>. The gnuwin32 packages 135e5dd7070Spatrick are the oldest and most well-tested way to get these tools. However, the 136e5dd7070Spatrick MSys utilities provided by git for Windows have been known to work. 137e5dd7070Spatrick Cygwin has worked in the past, but is not well tested. 138e5dd7070Spatrick If you don't already have the core utilies from some other source, get 139e5dd7070Spatrick gnuwin32 from <a href="http://getgnuwin32.sourceforge.net/"> 140e5dd7070Spatrick http://getgnuwin32.sourceforge.net/</a>.</li> 141e5dd7070Spatrick </ul> 142e5dd7070Spatrick </li> 143e5dd7070Spatrick 144e5dd7070Spatrick <li>Check out LLVM and Clang: 145e5dd7070Spatrick <ul> 146e5dd7070Spatrick <li><tt>git clone https://github.com/llvm/llvm-project.git</tt></li> 147e5dd7070Spatrick </ul> 148e5dd7070Spatrick <p><em>Note</em>: Some Clang tests are sensitive to the line endings. Ensure 149e5dd7070Spatrick that checking out the files does not convert LF line endings to CR+LF. If 150e5dd7070Spatrick you're using git on Windows, make sure your <tt>core.autocrlf</tt> setting 151e5dd7070Spatrick is false.</p> 152e5dd7070Spatrick </li> 153e5dd7070Spatrick <li>Run CMake to generate the Visual Studio solution and project files: 154e5dd7070Spatrick <ul> 155a9ac8606Spatrick <li><tt>cd llvm-project</tt></li> 156e5dd7070Spatrick <li><tt>mkdir build</tt> (for building without polluting the source dir)</li> 157e5dd7070Spatrick <li><tt>cd build</tt></li> 158e5dd7070Spatrick <li> 159e5dd7070Spatrick If you are using Visual Studio 2017: 160e5dd7070Spatrick <tt>cmake -DLLVM_ENABLE_PROJECTS=clang -G "Visual Studio 15 2017" -A x64 -Thost=x64 ..\llvm</tt><br/> 161e5dd7070Spatrick <tt>-Thost=x64</tt> is required, since the 32-bit linker will run out of memory. 162e5dd7070Spatrick </li> 163e5dd7070Spatrick <li>To generate x86 binaries instead of x64, pass <tt>-A Win32</tt>.</li> 164e5dd7070Spatrick <li>See the <a href="https://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for 165e5dd7070Spatrick more information on other configuration options for CMake.</li> 166e5dd7070Spatrick <li>The above, if successful, will have created an LLVM.sln file in the 167e5dd7070Spatrick <tt>build</tt> directory. 168e5dd7070Spatrick </ul> 169e5dd7070Spatrick </li> 170e5dd7070Spatrick <li>Build Clang: 171e5dd7070Spatrick <ul> 172e5dd7070Spatrick <li>Open LLVM.sln in Visual Studio.</li> 173e5dd7070Spatrick <li>Build the "clang" project for just the compiler driver and front end, or 174e5dd7070Spatrick the "ALL_BUILD" project to build everything, including tools.</li> 175e5dd7070Spatrick </ul> 176e5dd7070Spatrick </li> 177e5dd7070Spatrick <li>Try it out (assuming you added llvm/debug/bin to your path). (See the 178e5dd7070Spatrick running examples from above.)</li> 179e5dd7070Spatrick <li>See <a href="hacking.html#testingWindows"> 180e5dd7070Spatrick Hacking on clang - Testing using Visual Studio on Windows</a> for information 181e5dd7070Spatrick on running regression tests on Windows.</li> 182e5dd7070Spatrick</ol> 183e5dd7070Spatrick 184e5dd7070Spatrick<h3 id="buildWindowsNinja">Using Ninja alongside Visual Studio</h3> 185e5dd7070Spatrick 186e5dd7070Spatrick<p>We recommend that developers who want the fastest incremental builds use the 187e5dd7070Spatrick<a href="https://ninja-build.org/">Ninja build system</a>. You can use the 188e5dd7070Spatrickgenerated Visual Studio project files to edit Clang source code and generate a 189e5dd7070Spatricksecond build directory next to it for running the tests with these steps:</p> 190e5dd7070Spatrick 191e5dd7070Spatrick<ol> 192e5dd7070Spatrick <li>Check out clang and LLVM as described above</li> 193e5dd7070Spatrick <li>Open a developer command prompt with the appropriate environment. 194e5dd7070Spatrick <ul> 195e5dd7070Spatrick <li>If you open the start menu and search for "Command Prompt", you should 196e5dd7070Spatrick see shortcuts created by Visual Studio to do this. To use native x64 197e5dd7070Spatrick tools, choose the one titled "x64 Native Tools Command Prompt for VS 198e5dd7070Spatrick 2017".</li> 199e5dd7070Spatrick <li> Alternatively, launch a regular <tt>cmd</tt> prompt and run the 200e5dd7070Spatrick appropriate vcvarsall.bat incantation. To get the 2017 x64 tools, this 201e5dd7070Spatrick would be:<br/> 202e5dd7070Spatrick <tt>"C:\Program Files (x86)\Microsoft Visual 203e5dd7070Spatrick Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" x64</tt> 204e5dd7070Spatrick </li> 205e5dd7070Spatrick </ul> 206e5dd7070Spatrick </li> 207e5dd7070Spatrick <li><tt>mkdir build_ninja</tt> (or <tt>build</tt>, or use your own 208e5dd7070Spatrick organization)</li> 209e5dd7070Spatrick <li><tt>cd build_ninja</tt></li> 210e5dd7070Spatrick <li><tt>set CC=cl</tt> (necessary to force CMake to choose MSVC over mingw GCC 211e5dd7070Spatrick if you have it installed)</li> 212e5dd7070Spatrick <li><tt>set CXX=cl</tt></li> 213*12c85518Srobert <li><tt>cmake -GNinja -DLLVM_ENABLE_PROJECTS=clang ..\llvm</tt></li> 214e5dd7070Spatrick <li><tt>ninja clang</tt> This will build just clang.</li> 215e5dd7070Spatrick <li><tt>ninja check-clang</tt> This will run the clang tests.</li> 216e5dd7070Spatrick</ol> 217e5dd7070Spatrick 218e5dd7070Spatrick<h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2> 219e5dd7070Spatrick 220e5dd7070Spatrick<p>The <tt>clang</tt> tool is the compiler driver and front-end, which is 221e5dd7070Spatrickdesigned to be a drop-in replacement for the <tt>gcc</tt> command. Here are 222e5dd7070Spatricksome examples of how to use the high-level driver: 223e5dd7070Spatrick</p> 224e5dd7070Spatrick 225e5dd7070Spatrick<pre class="code"> 226e5dd7070Spatrick$ <b>cat t.c</b> 227e5dd7070Spatrick#include <stdio.h> 228e5dd7070Spatrickint main(int argc, char **argv) { printf("hello world\n"); } 229e5dd7070Spatrick$ <b>clang t.c</b> 230e5dd7070Spatrick$ <b>./a.out</b> 231e5dd7070Spatrickhello world 232e5dd7070Spatrick</pre> 233e5dd7070Spatrick 234e5dd7070Spatrick<p>The 'clang' driver is designed to work as closely to GCC as possible to 235e5dd7070Spatrick maximize portability. The only major difference between the two is that 236e5dd7070Spatrick Clang defaults to gnu99 mode while GCC defaults to gnu89 mode. If you see 237e5dd7070Spatrick weird link-time errors relating to inline functions, try passing -std=gnu89 238e5dd7070Spatrick to clang.</p> 239e5dd7070Spatrick 240e5dd7070Spatrick<h2>Examples of using Clang</h2> 241e5dd7070Spatrick 242e5dd7070Spatrick<!-- Thanks to 243e5dd7070Spatrick http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings 244e5dd7070SpatrickSite suggested using pre in CSS, but doesn't work in IE, so went for the <pre> 245e5dd7070Spatricktag. --> 246e5dd7070Spatrick 247e5dd7070Spatrick<pre class="code"> 248e5dd7070Spatrick$ <b>cat ~/t.c</b> 249e5dd7070Spatricktypedef float V __attribute__((vector_size(16))); 250e5dd7070SpatrickV foo(V a, V b) { return a+b*a; } 251e5dd7070Spatrick</pre> 252e5dd7070Spatrick 253e5dd7070Spatrick 254e5dd7070Spatrick<h3>Preprocessing:</h3> 255e5dd7070Spatrick 256e5dd7070Spatrick<pre class="code"> 257e5dd7070Spatrick$ <b>clang ~/t.c -E</b> 258e5dd7070Spatrick# 1 "/Users/sabre/t.c" 1 259e5dd7070Spatrick 260e5dd7070Spatricktypedef float V __attribute__((vector_size(16))); 261e5dd7070Spatrick 262e5dd7070SpatrickV foo(V a, V b) { return a+b*a; } 263e5dd7070Spatrick</pre> 264e5dd7070Spatrick 265e5dd7070Spatrick 266e5dd7070Spatrick<h3>Type checking:</h3> 267e5dd7070Spatrick 268e5dd7070Spatrick<pre class="code"> 269e5dd7070Spatrick$ <b>clang -fsyntax-only ~/t.c</b> 270e5dd7070Spatrick</pre> 271e5dd7070Spatrick 272e5dd7070Spatrick 273e5dd7070Spatrick<h3>GCC options:</h3> 274e5dd7070Spatrick 275e5dd7070Spatrick<pre class="code"> 276e5dd7070Spatrick$ <b>clang -fsyntax-only ~/t.c -pedantic</b> 277e5dd7070Spatrick/Users/sabre/t.c:2:17: <span style="color:magenta">warning:</span> extension used 278e5dd7070Spatrick<span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span> 279e5dd7070Spatrick<span style="color:blue"> ^</span> 280e5dd7070Spatrick1 diagnostic generated. 281e5dd7070Spatrick</pre> 282e5dd7070Spatrick 283e5dd7070Spatrick 284e5dd7070Spatrick<h3>Pretty printing from the AST:</h3> 285e5dd7070Spatrick 286e5dd7070Spatrick<p>Note, the <tt>-cc1</tt> argument indicates the compiler front-end, and 287e5dd7070Spatricknot the driver, should be run. The compiler front-end has several additional 288e5dd7070SpatrickClang specific features which are not exposed through the GCC compatible driver 289e5dd7070Spatrickinterface.</p> 290e5dd7070Spatrick 291e5dd7070Spatrick<pre class="code"> 292e5dd7070Spatrick$ <b>clang -cc1 ~/t.c -ast-print</b> 293e5dd7070Spatricktypedef float V __attribute__(( vector_size(16) )); 294e5dd7070SpatrickV foo(V a, V b) { 295e5dd7070Spatrick return a + b * a; 296e5dd7070Spatrick} 297e5dd7070Spatrick</pre> 298e5dd7070Spatrick 299e5dd7070Spatrick 300e5dd7070Spatrick<h3>Code generation with LLVM:</h3> 301e5dd7070Spatrick 302e5dd7070Spatrick<pre class="code"> 303e5dd7070Spatrick$ <b>clang ~/t.c -S -emit-llvm -o -</b> 304e5dd7070Spatrickdefine <4 x float> @foo(<4 x float> %a, <4 x float> %b) { 305e5dd7070Spatrickentry: 306e5dd7070Spatrick %mul = mul <4 x float> %b, %a 307e5dd7070Spatrick %add = add <4 x float> %mul, %a 308e5dd7070Spatrick ret <4 x float> %add 309e5dd7070Spatrick} 310e5dd7070Spatrick$ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i> 311e5dd7070Spatrick... 312e5dd7070Spatrick_foo: 313e5dd7070SpatrickLeh_func_begin1: 314e5dd7070Spatrick mulps %xmm0, %xmm1 315e5dd7070Spatrick addps %xmm1, %xmm0 316e5dd7070Spatrick ret 317e5dd7070SpatrickLeh_func_end1: 318e5dd7070Spatrick</pre> 319e5dd7070Spatrick 320e5dd7070Spatrick</div> 321e5dd7070Spatrick</body> 322e5dd7070Spatrick</html> 323