clang/www/get_started.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=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 &lt;stdio.h&gt;
 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 &lt;4 x float&gt; @foo(&lt;4 x float&gt; %a, &lt;4 x float&gt; %b) {
 305 entry:
 306          %mul = mul &lt;4 x float&gt; %b, %a
 307          %add = add &lt;4 x float&gt; %mul, %a
 308          ret &lt;4 x float&gt; %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>