Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 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 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 18 | <p>This page gives you the shortest path to checking out Clang and demos a few |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 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 |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 21 | involved</a> with the Clang community.</p> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 22 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 23 | <h2>A Word of Warning</h2> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 24 | |
| 25 | <p>While this work aims to provide a fully functional C/C++/ObjC front-end, it |
Daniel Dunbar | 05fc1c2 | 2009-05-24 01:00:12 +0000 | [diff] [blame] | 26 | is still relatively new and under heavy development. Currently we believe clang |
| 27 | to be very usable as a C and Objective-C compiler, however there is no real C++ |
| 28 | support yet (this is obviously a big project). Additionally, for C and |
| 29 | Objective-C:</p> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 30 | |
| 31 | <ol> |
Chris Lattner | d825883 | 2009-02-25 05:35:47 +0000 | [diff] [blame] | 32 | <li>The semantic analyzer does not produce all of the warnings it should.</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 33 | <li>We don't consider the API to be stable yet, and reserve the right to |
| 34 | change fundamental things.</li> |
Daniel Dunbar | 05fc1c2 | 2009-05-24 01:00:12 +0000 | [diff] [blame] | 35 | <li>Only the X86-32 and X86-64 targets have been well tested.</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 36 | </ol> |
| 37 | |
Daniel Dunbar | 05fc1c2 | 2009-05-24 01:00:12 +0000 | [diff] [blame] | 38 | <p>If you run into problems, please file |
Daniel Dunbar | ce9f496 | 2009-05-24 01:40:10 +0000 | [diff] [blame] | 39 | bugs in <a href="http://llvm.org/bugs/">LLVM Bugzilla</a> or bring up the issue |
Daniel Dunbar | 05fc1c2 | 2009-05-24 01:00:12 +0000 | [diff] [blame] | 40 | on the |
Chris Lattner | d825883 | 2009-02-25 05:35:47 +0000 | [diff] [blame] | 41 | <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev">Clang development |
| 42 | mailing list</a>.</p> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 43 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 44 | <h2 id="build">Building Clang and Working with the Code</h2> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 45 | |
Eli Friedman | d1e1ef3 | 2009-08-03 19:42:28 +0000 | [diff] [blame] | 46 | <h3 id="buildNix">On Unix-like Systems</h3> |
| 47 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 48 | <p>If you would like to check out and build Clang, the current procedure is as |
| 49 | follows:</p> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 50 | |
| 51 | <ol> |
Anton Korobeynikov | 1816e48 | 2009-08-06 13:00:08 +0000 | [diff] [blame] | 52 | <li>Get the required tools. |
| 53 | <ul> |
| 54 | <li>See |
| 55 | <a href="http://llvm.org/docs/GettingStarted.html#requirements"> |
| 56 | Getting Started with the LLVM System - Requirements</a>.</li> |
| 57 | <li>Note also that Python is needed for running the test suite. |
| 58 | Get it at: <a href="http://www.python.org/download"> |
| 59 | http://www.python.org/download</a></li> |
| 60 | </ul> |
| 61 | |
Chris Lattner | 357f7ce | 2009-08-20 06:17:11 +0000 | [diff] [blame] | 62 | <li>Checkout LLVM:</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 63 | <ul> |
Chris Lattner | 357f7ce | 2009-08-20 06:17:11 +0000 | [diff] [blame] | 64 | <li>Change directory to where you want the llvm directory placed.</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 65 | <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 66 | </ul> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 67 | <li>Checkout Clang:</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 68 | <ul> |
Chris Lattner | 357f7ce | 2009-08-20 06:17:11 +0000 | [diff] [blame] | 69 | <li><tt>cd llvm/tools</tt> |
| 70 | <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> |
| 71 | </ul> |
| 72 | <li>Build LLVM and Clang:</li> |
| 73 | <ul> |
| 74 | <li><tt>cd ..</tt> (back to llvm)</li> |
| 75 | <li><tt>./configure</tt></li> |
| 76 | <li><tt>make</tt></li> |
| 77 | <li>This builds both LLVM and Clang for debug mode.</li> |
| 78 | <li>Note: For subsequent Clang development, you can just do make at the |
| 79 | clang directory level.</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 80 | </ul> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 81 | <li>If you intend to work on Clang C++ support, you may need to tell it how |
| 82 | to find your C++ standard library headers. If Clang cannot find your |
Chris Lattner | ca8c49f | 2009-03-10 16:01:44 +0000 | [diff] [blame] | 83 | system libstdc++ headers, please follow these instructions:</li> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 84 | <ul> |
Chris Lattner | ca8c49f | 2009-03-10 16:01:44 +0000 | [diff] [blame] | 85 | <li>'<tt>touch empty.cpp; gcc -v empty.cpp -fsyntax-only</tt>' to get the |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 86 | path.</li> |
| 87 | <li>Look for the comment "FIXME: temporary hack: |
Chris Lattner | ca8c49f | 2009-03-10 16:01:44 +0000 | [diff] [blame] | 88 | hard-coded paths" in <tt>clang/lib/Frontend/InitHeaderSearch.cpp</tt> and |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 89 | change the lines below to include that path.</li> |
| 90 | </ul> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 91 | <li>Try it out (assuming you add llvm/Debug/bin to your path):</li> |
| 92 | <ul> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 93 | <li><tt>clang-cc --help</tt></li> |
| 94 | <li><tt>clang-cc file.c -fsyntax-only</tt> (check for correctness)</li> |
| 95 | <li><tt>clang-cc file.c -ast-dump</tt> (internal debug dump of ast)</li> |
| 96 | <li><tt>clang-cc file.c -ast-view</tt> (<a |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 97 | href="http://llvm.org/docs/ProgrammersManual.html#ViewGraph">set up graphviz |
| 98 | and rebuild llvm first</a>)</li> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 99 | <li><tt>clang-cc file.c -emit-llvm</tt> (print out unoptimized llvm code)</li> |
| 100 | <li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 101 | llvm-dis</tt> (print out optimized llvm code)</li> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 102 | <li><tt>clang-cc file.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 103 | > file.s</tt> (output native machine code)</li> |
| 104 | </ul> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 105 | <p><em>Note</em>: Here <tt>clang-cc</tt> is the "low-level" frontend |
| 106 | executable that is similar in purpose to <tt>cc1</tt>. Clang also has a <a |
| 107 | href="#driver">high-level compiler driver</a> that acts as a drop-in |
| 108 | replacement for <tt>gcc</tt>. |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 109 | </ol> |
| 110 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 111 | <p>Note that the C front-end uses LLVM, but does not depend on llvm-gcc. If you |
| 112 | encounter problems with building Clang, make sure you have the latest SVN |
| 113 | version of LLVM. LLVM contains support libraries for Clang that will be updated |
| 114 | as well as development on Clang progresses.</p> |
Ted Kremenek | 675a9ba | 2008-02-08 07:32:26 +0000 | [diff] [blame] | 115 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 116 | <h3>Simultaneously Building Clang and LLVM:</h3> |
Eric Christopher | 562b4f3 | 2008-02-08 07:10:48 +0000 | [diff] [blame] | 117 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 118 | <p>Once you have checked out Clang into the llvm source tree it will build along |
| 119 | with the rest of <tt>llvm</tt>. To build all of LLVM and Clang together all at |
| 120 | once simply run <tt>make</tt> from the root LLVM directory.</p> |
| 121 | |
| 122 | <p><em>Note:</em> Observe that Clang is technically part of a separate |
| 123 | Subversion repository. As mentioned above, the latest Clang sources are tied to |
| 124 | the latest sources in the LLVM tree. You can update your toplevel LLVM project |
| 125 | and all (possibly unrelated) projects inside it with <tt><b>make |
| 126 | update</b></tt>. This will run <tt>svn update</tt> on all subdirectories related |
| 127 | to subversion. </p> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 128 | |
Eli Friedman | d1e1ef3 | 2009-08-03 19:42:28 +0000 | [diff] [blame] | 129 | <h3 id="buildWindows">Using Visual Studio</h3> |
| 130 | |
| 131 | <p>The following details setting up for and building Clang on Windows using |
| 132 | Visual Studio:</p> |
| 133 | |
| 134 | <ol> |
| 135 | <li>Get the required tools:</li> |
| 136 | <ul> |
| 137 | <li><b>Subversion</b>. Source code control program. Get it from: |
| 138 | <a href="http://subversion.tigris.org/getting.html"> |
| 139 | http://subversion.tigris.org/getting.html</a></li> |
| 140 | <li><b>cmake</b>. This is used for generating Visual Studio solution and |
| 141 | project files. Get it from: |
| 142 | <a href="http://www.cmake.org/cmake/resources/software.html"> |
| 143 | http://www.cmake.org/cmake/resources/software.html</a></li> |
Cedric Venet | 6bfc8b6 | 2009-09-27 10:34:36 +0000 | [diff] [blame^] | 144 | <li><b>Visual Studio 2005 or 2008</b></li> |
Chris Lattner | 357f7ce | 2009-08-20 06:17:11 +0000 | [diff] [blame] | 145 | <li><b>Python</b>. This is needed only if you will be running the tests |
Eli Friedman | d1e1ef3 | 2009-08-03 19:42:28 +0000 | [diff] [blame] | 146 | (which is essential, if you will be developing for clang). |
| 147 | Get it from: |
| 148 | <a href="http://www.python.org/download"> |
| 149 | http://www.python.org/download</a></li> |
Chris Lattner | 357f7ce | 2009-08-20 06:17:11 +0000 | [diff] [blame] | 150 | <li><b>GnuWin32 tools</b> |
| 151 | These are also necessary for running the tests. |
| 152 | (Note that the grep from MSYS or Cygwin doesn't work with the tests |
| 153 | because of embedded double-quotes in the search strings. The GNU |
| 154 | grep does work in this case.) |
| 155 | Get them from <a href="http://getgnuwin32.sourceforge.net"> |
| 156 | http://getgnuwin32.sourceforge.net</a>.</li> |
Eli Friedman | d1e1ef3 | 2009-08-03 19:42:28 +0000 | [diff] [blame] | 157 | </ul> |
| 158 | |
| 159 | <li>Checkout LLVM:</li> |
| 160 | <ul> |
| 161 | <li><tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> |
| 162 | </ul> |
| 163 | <li>Checkout Clang:</li> |
| 164 | <ul> |
| 165 | <li><tt>cd llvm\tools</tt> |
| 166 | <li><tt>svn co http://llvm.org/svn/llvm-project/cfe/trunk clang</tt></li> |
| 167 | </ul> |
| 168 | <li>Run cmake to generate the Visual Studio solution and project files:</li> |
| 169 | <ul> |
| 170 | <li><tt>cd ..</tt> (Change directory back to the llvm top.)</li> |
| 171 | <li><tt>cmake .</tt></li> |
| 172 | <li>The above, if successful, will have created an LLVM.sln file in the |
| 173 | llvm directory. |
| 174 | </ul> |
| 175 | <li>Build Clang:</li> |
| 176 | <ul> |
| 177 | <li>Open LLVM.sln in Visual Studio.</li> |
| 178 | <li>Build the "clang-cc" project for just the compiler front end. |
| 179 | Alternatively, build the "clang" project for the compiler driver |
| 180 | (note that the driver is currently broken on Windows), |
| 181 | or the "ALL_BUILD" project to build everything, including tools.</li> |
| 182 | </ul> |
| 183 | <li>Try it out (assuming you added llvm/debug/bin to your path). (See the |
| 184 | running examples from above.)</li> |
| 185 | <li>See <a href="hacking.html#testingWindows"> |
| 186 | Hacking on clang - Testing using Visual Studio on Windows</a> for information |
| 187 | on running regression tests on Windows.</li> |
| 188 | </ol> |
| 189 | |
| 190 | <p>Note that once you have checked out both llvm and clang, to synchronize |
| 191 | to the latest code base, use the <tt>svn update</tt> command in both the |
| 192 | llvm and llvm\tools\clang directories, as they are separate repositories.</p> |
| 193 | |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 194 | <a name="driver"><h2>High-Level Compiler Driver (Drop-in Substitute for GCC)</h2></a> |
| 195 | |
| 196 | <p>While the <tt>clang-cc</tt> executable is a low-level frontend executable |
| 197 | that can perform code generation, program analysis, and other actions, it is not |
| 198 | designed to be a drop-in replacement for GCC's <tt>cc</tt>. For this purpose, |
| 199 | use the high-level driver, aptly named <tt>clang</tt>. Here are some |
| 200 | examples of how to use the high-level driver: |
| 201 | </p> |
| 202 | |
| 203 | <pre class="code"> |
| 204 | $ <b>cat t.c</b> |
| 205 | #include <stdio.h> |
| 206 | int main(int argc, char **argv) { printf("hello world\n"); } |
| 207 | $ <b>clang t.c</b> |
| 208 | $ <b>./a.out</b> |
| 209 | hello world |
| 210 | </pre> |
| 211 | |
| 212 | <h2>Examples of using Clang</h2> |
| 213 | |
| 214 | <p>The high-level driver <tt>clang</tt> is designed to understand most of GCC's |
| 215 | options, and the lower-level <tt>clang-cc</tt> executable also directly takes |
| 216 | many of GCC's options. You can see which options <tt>clang-cc</tt> accepts with |
| 217 | '<tt>clang-cc --help</tt>'. Here are a few examples of using <tt>clang</tt> and |
| 218 | <tt>clang-cc</tt>:</p> |
| 219 | |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 220 | <!-- Thanks to |
| 221 | http://shiflett.org/blog/2006/oct/formatting-and-highlighting-php-code-listings |
| 222 | Site suggested using pre in CSS, but doesn't work in IE, so went for the <pre> |
| 223 | tag. --> |
| 224 | |
| 225 | <pre class="code"> |
| 226 | $ <b>cat ~/t.c</b> |
| 227 | typedef float V __attribute__((vector_size(16))); |
| 228 | V foo(V a, V b) { return a+b*a; } |
| 229 | </pre> |
| 230 | |
| 231 | |
Ted Kremenek | 35f29c5 | 2008-06-17 13:48:36 +0000 | [diff] [blame] | 232 | <h3>Preprocessing:</h3> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 233 | |
| 234 | <pre class="code"> |
| 235 | $ <b>clang ~/t.c -E</b> |
| 236 | # 1 "/Users/sabre/t.c" 1 |
| 237 | |
| 238 | typedef float V __attribute__((vector_size(16))); |
| 239 | |
| 240 | V foo(V a, V b) { return a+b*a; } |
| 241 | </pre> |
| 242 | |
| 243 | |
Ted Kremenek | 35f29c5 | 2008-06-17 13:48:36 +0000 | [diff] [blame] | 244 | <h3>Type checking:</h3> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 245 | |
| 246 | <pre class="code"> |
| 247 | $ <b>clang -fsyntax-only ~/t.c</b> |
| 248 | </pre> |
| 249 | |
| 250 | |
Ted Kremenek | 35f29c5 | 2008-06-17 13:48:36 +0000 | [diff] [blame] | 251 | <h3>GCC options:</h3> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 252 | |
| 253 | <pre class="code"> |
| 254 | $ <b>clang -fsyntax-only ~/t.c -pedantic</b> |
| 255 | /Users/sabre/t.c:2:17: warning: extension used |
| 256 | typedef float V __attribute__((vector_size(16))); |
| 257 | ^ |
| 258 | 1 diagnostic generated. |
| 259 | </pre> |
| 260 | |
| 261 | |
Ted Kremenek | 35f29c5 | 2008-06-17 13:48:36 +0000 | [diff] [blame] | 262 | <h3>Pretty printing from the AST:</h3> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 263 | |
| 264 | <pre class="code"> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 265 | $ <b>clang-cc ~/t.c -ast-print</b> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 266 | typedef float V __attribute__(( vector_size(16) )); |
| 267 | V foo(V a, V b) { |
| 268 | return a + b * a; |
| 269 | } |
| 270 | </pre> |
| 271 | |
| 272 | |
Ted Kremenek | 35f29c5 | 2008-06-17 13:48:36 +0000 | [diff] [blame] | 273 | <h3>Code generation with LLVM:</h3> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 274 | |
| 275 | <pre class="code"> |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 276 | $ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llvm-dis</b> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 277 | define <4 x float> @foo(<4 x float> %a, <4 x float> %b) { |
| 278 | entry: |
| 279 | %mul = mul <4 x float> %b, %a |
| 280 | %add = add <4 x float> %mul, %a |
| 281 | ret <4 x float> %add |
| 282 | } |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 283 | $ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=ppc32 -mcpu=g5</b> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 284 | .. |
| 285 | _foo: |
| 286 | vmaddfp v2, v3, v2, v2 |
| 287 | blr |
Ted Kremenek | 9b16da3 | 2009-03-27 16:32:57 +0000 | [diff] [blame] | 288 | $ <b>clang-cc ~/t.c -emit-llvm -o - | llvm-as | opt -std-compile-opts | llc -march=x86 -mcpu=yonah</b> |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 289 | .. |
| 290 | _foo: |
| 291 | mulps %xmm0, %xmm1 |
| 292 | addps %xmm0, %xmm1 |
| 293 | movaps %xmm1, %xmm0 |
| 294 | ret |
| 295 | </pre> |
| 296 | |
Eric Christopher | 7dc0e57 | 2008-02-08 06:45:49 +0000 | [diff] [blame] | 297 | </div> |
| 298 | </body> |
| 299 | </html> |