326 lines · html
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=utf-8">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 few19options. 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">getting21involved</a> with the Clang community. If you run into problems, please file22bugs on <a href="https://github.com/llvm/llvm-project/issues">the LLVM bug tracker</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 as34follows:</p>35 36<ol>37 <li>Get the required tools.38 <ul>39 <li>See40 <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>This builds both LLVM and Clang in release mode. Alternatively, if73 you need a debug build, switch Release to Debug. See74 <a href="https://llvm.org/docs/CMake.html#frequently-used-cmake-variables">frequently used cmake variables</a>75 for more options.76 </li>77 <li><tt>cmake -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" ../llvm</tt></li>78 <li><tt>make</tt></li>79 <li>Note: For subsequent Clang development, you can just run80 <tt>make clang</tt>.</li>81 <li>CMake allows you to generate project files for several IDEs: Xcode,82 Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks generator),83 KDevelop3. For more details see84 <a href="https://llvm.org/docs/CMake.html">Building LLVM with CMake</a>85 page.</li>86 </ul>87 </li>88 89 <li>On Linux, you may need GCC runtime libraries (e.g. <tt>crtbeginS.o,90 libstdc++.so</tt>) and libstdc++ headers. In general, Clang will detect91 well-known GCC installation paths matching the target triple (configured at92 build time (see <tt>clang --version</tt>); overriden by93 <tt>--target=</tt>) and use the largest version. If your configuration fits94 none of the standard scenarios, you can set <tt>--gcc-install-dir=</tt> to95 the GCC installation directory (something like96 <tt>/usr/lib/gcc/$triple/$major</tt>). If your GCC installation is under97 <tt>/usr/lib/gcc</tt> but uses a different triple, you can set98 <tt>--gcc-triple=$triple</tt>.99 </li>100 <li>Try it out (assuming you add llvm/build/bin to your path):101 <ul>102 <li><tt>clang --help</tt></li>103 <li><tt>clang file.c -fsyntax-only</tt> (check for correctness)</li>104 <li><tt>clang file.c -S -emit-llvm -o -</tt> (print out unoptimized llvm code)</li>105 <li><tt>clang file.c -S -emit-llvm -o - -O3</tt></li>106 <li><tt>clang file.c -S -O3 -o -</tt> (output native machine code)</li>107 </ul>108 </li>109 <li>Run the testsuite:110 <ul>111 <li><tt>make check-clang</tt></li>112 </ul>113 </li>114</ol>115 116<h3 id="buildWindows">Using Visual Studio</h3>117 118<p>The following details setting up for and building Clang on Windows using119Visual Studio:</p>120 121<ol>122 <li>Get the required tools:123 <ul>124 <li><b>Git</b>. Source code control program. Get it from:125 <a href="https://git-scm.com/download">126 https://git-scm.com/download</a></li>127 <li><b>CMake</b>. This is used for generating Visual Studio solution and128 project files. Get it from:129 <a href="https://cmake.org/download/">130 https://cmake.org/download/</a></li>131 <li><b>Visual Studio 2019 16.7 or later</b>. This tutorial assumes Visual Studio 2022.</li>132 <li><b>Python</b>. It is used to run the clang test suite. Get it from:133 <a href="https://www.python.org/download/">134 https://www.python.org/download/</a></li>135 <li><b>GnuWin32 tools</b>136 The Clang and LLVM test suite use various GNU core utilities, such as137 <tt>grep</tt>, <tt>sed</tt>, and <tt>find</tt>. The gnuwin32 packages138 are the oldest and most well-tested way to get these tools. However, the139 MSys utilities provided by git for Windows have been known to work.140 Cygwin has worked in the past, but is not well tested.141 If you don't already have the core utilies from some other source, get142 gnuwin32 from <a href="http://getgnuwin32.sourceforge.net/">143 http://getgnuwin32.sourceforge.net/</a>.</li>144 </ul>145 </li>146 147 <li>Check out LLVM and Clang:148 <ul>149 <li><tt>git clone https://github.com/llvm/llvm-project.git</tt></li>150 </ul>151 <p><em>Note</em>: Some Clang tests are sensitive to the line endings. Ensure152 that checking out the files does not convert LF line endings to CR+LF. If153 you're using git on Windows, make sure your <tt>core.autocrlf</tt> setting154 is false.</p>155 </li>156 <li>Run CMake to generate the Visual Studio solution and project files:157 <ul>158 <li><tt>cd llvm-project</tt></li>159 <li><tt>mkdir build</tt> (for building without polluting the source dir)</li>160 <li><tt>cd build</tt></li>161 <li>162 If you are using Visual Studio 2022:163 <tt>cmake -DLLVM_ENABLE_PROJECTS=clang -G "Visual Studio 17 2022" -A x64 -Thost=x64 ..\llvm</tt><br/>164 <tt>-Thost=x64</tt> is required, since the 32-bit linker will run out of memory.165 </li>166 <li>To generate x86 binaries instead of x64, pass <tt>-A Win32</tt>.</li>167 <li>See the <a href="https://www.llvm.org/docs/CMake.html">LLVM CMake guide</a> for168 more information on other configuration options for CMake.</li>169 <li>The above, if successful, will have created an LLVM.sln file in the170 <tt>build</tt> directory.171 </ul>172 </li>173 <li>Build Clang:174 <ul>175 <li>Open LLVM.sln in Visual Studio.</li>176 <li>Build the "clang" project for just the compiler driver and front end, or177 the "ALL_BUILD" project to build everything, including tools.</li>178 </ul>179 </li>180 <li>Try it out (assuming you added llvm/debug/bin to your path). (See the181 running examples from above.)</li>182 <li>See <a href="hacking.html#testingWindows">183 Hacking on clang - Testing using Visual Studio on Windows</a> for information184 on running regression tests on Windows.</li>185</ol>186 187<h3 id="buildWindowsNinja">Using Ninja alongside Visual Studio</h3>188 189<p>We recommend that developers who want the fastest incremental builds use the190<a href="https://ninja-build.org/">Ninja build system</a>. You can use the191generated Visual Studio project files to edit Clang source code and generate a192second build directory next to it for running the tests with these steps:</p>193 194<ol>195 <li>Check out clang and LLVM as described above</li>196 <li>Open a developer command prompt with the appropriate environment.197 <ul>198 <li>If you open the start menu and search for "Command Prompt", you should199 see shortcuts created by Visual Studio to do this. To use native x64200 tools, choose the one titled "x64 Native Tools Command Prompt for VS201 2022".</li>202 <li> Alternatively, launch a regular <tt>cmd</tt> prompt and run the203 appropriate vcvarsall.bat incantation. To get the 2022 x64 tools, this204 would be:<br/>205 <tt>"C:\Program Files\Microsoft Visual206 Studio\2022\Community\VC\Auxiliary\Build\vcvarsall.bat" x64</tt>207 </li>208 </ul>209 </li>210 <li><tt>mkdir build_ninja</tt> (or <tt>build</tt>, or use your own211 organization)</li>212 <li><tt>cd build_ninja</tt></li>213 <li><tt>set CC=cl</tt> (necessary to force CMake to choose MSVC over mingw GCC214 if you have it installed)</li>215 <li><tt>set CXX=cl</tt></li>216 <li><tt>cmake -GNinja -DLLVM_ENABLE_PROJECTS=clang ..\llvm</tt></li>217 <li><tt>ninja clang</tt> This will build just clang.</li>218 <li><tt>ninja check-clang</tt> This will run the clang tests.</li>219</ol>220 221<h2 id="driver">Clang Compiler Driver (Drop-in Substitute for GCC)</h2>222 223<p>The <tt>clang</tt> tool is the compiler driver and front-end, which is224designed to be a drop-in replacement for the <tt>gcc</tt> command. Here are225some examples of how to use the high-level driver:226</p>227 228<pre class="code">229$ <b>cat t.c</b>230#include <stdio.h>231int main(int argc, char **argv) { printf("hello world\n"); }232$ <b>clang t.c</b>233$ <b>./a.out</b>234hello world235</pre>236 237<p>The 'clang' driver is designed to work as closely to GCC as possible to238 maximize portability. The only major difference between the two is that239 Clang defaults to gnu99 mode while GCC defaults to gnu89 mode. If you see240 weird link-time errors relating to inline functions, try passing -std=gnu89241 to clang.</p>242 243<h2>Examples of using Clang</h2>244 245<!-- Thanks to246 http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings247Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre>248tag. -->249 250<pre class="code">251$ <b>cat ~/t.c</b>252typedef float V __attribute__((vector_size(16)));253V foo(V a, V b) { return a+b*a; }254</pre>255 256 257<h3>Preprocessing:</h3>258 259<pre class="code">260$ <b>clang ~/t.c -E</b>261# 1 "/Users/sabre/t.c" 1262 263typedef float V __attribute__((vector_size(16)));264 265V foo(V a, V b) { return a+b*a; }266</pre>267 268 269<h3>Type checking:</h3>270 271<pre class="code">272$ <b>clang -fsyntax-only ~/t.c</b>273</pre>274 275 276<h3>GCC options:</h3>277 278<pre class="code">279$ <b>clang -fsyntax-only ~/t.c -pedantic</b>280/Users/sabre/t.c:2:17: <span style="color:magenta">warning:</span> extension used281<span style="color:darkgreen">typedef float V __attribute__((vector_size(16)));</span>282<span style="color:blue"> ^</span>2831 diagnostic generated.284</pre>285 286 287<h3>Pretty printing from the AST:</h3>288 289<p>Note, the <tt>-cc1</tt> argument indicates the compiler front-end, and290not the driver, should be run. The compiler front-end has several additional291Clang specific features which are not exposed through the GCC compatible driver292interface.</p>293 294<pre class="code">295$ <b>clang -cc1 ~/t.c -ast-print</b>296typedef float V __attribute__(( vector_size(16) ));297V foo(V a, V b) {298 return a + b * a;299}300</pre>301 302 303<h3>Code generation with LLVM:</h3>304 305<pre class="code">306$ <b>clang ~/t.c -S -emit-llvm -o -</b>307define <4 x float> @foo(<4 x float> %a, <4 x float> %b) {308entry:309 %mul = mul <4 x float> %b, %a310 %add = add <4 x float> %mul, %a311 ret <4 x float> %add312}313$ <b>clang -fomit-frame-pointer -O3 -S -o - t.c</b> <i># On x86_64</i>314...315_foo:316Leh_func_begin1:317 mulps %xmm0, %xmm1318 addps %xmm1, %xmm0319 ret320Leh_func_end1:321</pre>322 323</div>324</body>325</html>326