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