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