Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / eb093fbf6fd2878c842f2f215362597475ef1817 / . / docs / GettingStarted.html
blob: 711b04cdc4ce05226d10a745df4785fe650f5cdc [file] [log] [blame]
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]3 <head>
4 <title>Getting Started with LLVM System</title>
5 </head>
6
7 <body bgcolor=white>
8 <center><h1>Getting Started with the LLVM System<br><font size=3>By: <a
9 href="mailto:gshi1@uiuc.edu">Guochun Shi</a>,
10 <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
11 <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>
12 </font></h1></center>
13
14 <!--=====================================================================-->
15 <h2><a name="Contents">Contents</a></h2>
16 <!--=====================================================================-->
17
18 <ul>
19 <li><a href="#overview">Overview</a>
20 <li><a href="#starting">Getting started with LLVM</a>
21 <ol>
22 <li><a href="#quickstart">Getting started quickly (a summary)</a>
23 <li><a href="#checkout">Checkout LLVM from CVS</a>
24 <li><a href="#terminology">Terminology and Notation</tt></a>
25 <li><a href="#objfiles">The location for object files</tt></a>
26 <li><a href="#config">Local Configuration Options</tt></a>
27 <li><a href="#environment">Setting up your environment</a>
28 <li><a href="#compile">Compiling the source code</a>
29 </ol>
30 <li><a href="#layout">Program layout</a>
31 <ol>
32 <li><a href="#cvsdir">CVS directories</a>
33 <li><a href="#dd"><tt>Depend</tt>, <tt>Debug</tt>, &amp;
34 <tt>Release</tt> directories</a></li>
35 <li><a href="#include"><tt>llvm/include</tt></a>
36 <li><a href="#lib"><tt>llvm/lib</tt></a>
37 <li><a href="#test"><tt>llvm/test</tt></a>
38 <li><a href="#tools"><tt>llvm/tools</tt></a>
39 </ol>
40 <li><a href="#tutorial">An example using the LLVM tool chain</a>
41 <li><a href="#links">Links</a>
42 </ul>
43
44
45 <!--=====================================================================-->
46 <center>
47 <h2><a name="overview"><b>Overview</b></a></h2>
48 </center>
49 <!--=====================================================================-->
50
51 <p>The <a href"starting">next section</a> of this guide is meant to get
52 you up and running with LLVM and to give you some basic information about
53 the LLVM environment. The <a href"#quickstart">first subsection</a> gives
54 a short summary for those who are already familiar with the system and
55 want to get started as quickly as possible.
56
57 <p>The later sections of this guide describe the <a
58 href"#layout">general layout</a> of the the LLVM source-tree, a <a
59 href="#tutorial">simple example</a> using the LLVM tool chain, and <a
60 href="#links">links</a> to find more information about LLVM or to get
61 help via e-mail.
62
63 <!--=====================================================================-->
64 <center>
65 <h2><a name="starting"><b>Getting Started</b></a></h2>
66 </center>
67 <!--=====================================================================-->
68
69
70 <!--=====================================================================-->
71 <h3><a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a></h3>
72 <!--=====================================================================-->
73
74 Here's the short story for getting up and running quickly with LLVM:
Chris Lattner96768ea2003-02-14 04:22:13 +0000[diff] [blame]75 <ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]76 <li>Find the path to the CVS repository containing LLVM (we'll call this <i>CVSROOTDIR</i>).
77 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
78 <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt>
79 <li><tt>cd llvm</tt>
80 <li>Edit <tt>Makefile.config</tt> to set local paths. This includes
81 setting the install location of the C frontend and the various paths
82 to the C and C++ compilers used to build LLVM itself.
83 <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
84 <li><tt>gmake -k |& tee gnumake.out
85 &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
Chris Lattner96768ea2003-02-14 04:22:13 +0000[diff] [blame]86 </ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]87
88 <p>See <a href="#environment">Setting up your environment</a> on tips to
89 simplify working with the LLVM front-end and compiled tools. See the
90 other sub-sections below for other useful details in working with LLVM,
91 or go straight to <a href="#layout">Program Layout</a> to learn about the
92 layout of the source code tree.
93
94 <!------------------------------------------------------------------------->
95 <h3><a name="terminology">Terminology and Notation</a></h3>
96 <!------------------------------------------------------------------------->
97
98 <p>Throughout this manual, the following names are used to denote paths
99 specific to the local system and working environment. <i>These are not
100 environment variables you need to set, but just strings used in the rest
101 of this document below.</i>. In any of the examples below, simply replace
102 each of these names with the appropriate pathname on your local system.
Chris Lattner1db872d2002-09-06 16:26:13 +0000[diff] [blame]103 All these paths are absolute:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]104 <ul>
105 </ul>
106
107 <!------------------------------------------------------------------------->
108 <h3><a name="checkout">Checkout LLVM from CVS</a></h3>
109 <!------------------------------------------------------------------------->
110
111 <p>Before checking out the source code, you will need to know the path to
112 the CVS repository containing LLVM source code (we'll call this
113 <i>CVSROOTDIR</i> below). Ask the person responsible for your local LLVM
114 installation to give you this path.
115
116 <p>To get a fresh copy of the entire source code, all you
117 need to do is check it out from CVS as follows:
118 <ul>
119 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
120 <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt></p>
121 </ul>
122
123 <p>This will create an '<tt>llvm</tt>' directory in the current
124 directory and fully populate it with the LLVM source code, Makefiles,
125 test directories, and local copies of documentation files.</p>
126
127 <!------------------------------------------------------------------------->
128 <h3><a name="config">Local Configuration Options</a></h3>
129 <!------------------------------------------------------------------------->
130
131 <p>The file <tt>llvm/Makefile.config</tt>
132 defines the following path variables
133 which are specific to a particular installation of LLVM.
134 These need to be modified only once after checking out a copy
135 of LLVM (if the default values do not already match your system):
136
137 <ul>
138 <p><li><i>CXX</i> = Path to C++ compiler to use.
139 <p><li><i>OBJ_ROOT</i> = Path to the llvm directory where
140 object files should be placed.
141 (See the Section on <a href=#objfiles>
142 The location for LLVM object files</a>
143 for more information.)
144 <p><li><i>LLVMGCCDIR</i> = Path to the location of the LLVM front-end
145 binaries and associated libraries.
146 <p><li><i>PURIFY</i> = Path to the purify program.
147 </ul>
148
149 In addition to settings in this file, you must set a
150 <tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
151 This environment variable is used to locate "system" libraries like
152 "<tt>-lc</tt>" and "<tt>-lm</tt>" when linking. This variable should be set
153 to the absolute path for the bytecode-libs subdirectory of the C front-end
154 install. For example, one might use
155 <tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the X86
156 version of the C front-end on our research machines.<p>
157
158 <!------------------------------------------------------------------------->
159 <h3><a name="objfiles">The location for LLVM object files</a></h3>
160 <!------------------------------------------------------------------------->
161
162 <p>The LLVM make system sends most output files generated during the build
163 into the directory defined by the variable OBJ_ROOT in
164 <tt>llvm/Makefile.config</tt>. This can be either just your normal LLVM
165 source tree or some other directory writable by you. You may wish to put
166 object files on a different filesystem either to keep them from being backed
167 up or to speed up local builds.
168
169 <p>If you do not wish to use a different location for object files (i.e.
170 you are building into the source tree directly), just set this variable to
171 ".".<p>
172
173 <!------------------------------------------------------------------------->
174 <h3><a name="environment">Setting up your environment</a></h3>
175 <!------------------------------------------------------------------------->
176
177 <i>NOTE: This step is optional but will set up your environment so you
178 can use the compiled LLVM tools with as little hassle as
179 possible.</i>)
180
181 <p>Add the following lines to your <tt>.cshrc</tt> (or the corresponding
182 lines to your <tt>.profile</tt> if you use a bourne shell derivative).
183
184 <pre>
185 # Make the C front end easy to use...
186 alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/llvm-gcc</tt>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame]187
188 # Make the LLVM tools easy to use...
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]189 setenv PATH <i>OBJ_ROOT</i>/llvm/tools/Debug:${PATH}
190 </pre>
191 The <tt>llvmgcc</tt> alias is useful because the C compiler is not
192 included in the CVS tree you just checked out.
Chris Lattner1db872d2002-09-06 16:26:13 +0000[diff] [blame]193
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]194 <p>The other <a href="#tools">LLVM tools</a> are part of the LLVM
195 source base and built when compiling LLVM. They will be built into the
196 <tt><i>OBJ_ROOT</i>/tools/Debug</tt> directory.</p>
197
198 <!------------------------------------------------------------------------->
199 <h3><a name="compile">Compiling the source code</a></h3>
200 <!------------------------------------------------------------------------->
201
202 <p>Every directory in the LLVM source tree includes a <tt>Makefile</tt> to
203 build it and any subdirectories that it contains. These makefiles require
204 that you use GNU Make (aka <tt>gmake</tt>) instead of <tt>make</tt> to
205 build them, but can
206 otherwise be used freely. To build the entire LLVM system, just enter the
207 top level <tt>llvm</tt> directory and type <tt>gmake</tt>. A few minutes
208 later you will hopefully have a freshly compiled toolchain waiting for you
209 in <tt><i>OBJ_ROOT</i>/llvm/tools/Debug</tt>. If you want to look at the
210 libraries that were compiled, look in
211 <tt><i>OBJ_ROOT</i>/llvm/lib/Debug</tt>.</p>
212
213 If you get an error about a <tt>/localhome</tt> directory, follow the
214 instructions in the section about <a href="#environment">Setting Up Your
215 Environment.</a>
216
217
218
219 <!--=====================================================================-->
220 <center>
221 <h2><a name="layout"><b>Program Layout</b></a></h2>
222 </center>
223 <!--=====================================================================-->
224
225 <p>One useful source of infomation about the LLVM sourcebase is the LLVM <a
226 href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
227 href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>. The
228 following is a brief introduction to code layout:</p>
229
230
231 <!------------------------------------------------------------------------->
232 <h3><a name="cvsdir"><tt>CVS</tt> directories</a></h3>
233 <!------------------------------------------------------------------------->
234
235 Every directory checked out of CVS will contain a <tt>CVS</tt> directory;
236 for the most part these can just be ignored.
237
238
239 <!------------------------------------------------------------------------->
240 <h3><a name="ddr"><tt>Depend</tt>, <tt>Debug</tt>, &amp; <tt>Release</tt>
Chris Lattner44ac6592002-08-09 16:14:56 +0000[diff] [blame]241 directories</a></h3>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]242 <!------------------------------------------------------------------------->
243
244 If you are building with the "<tt>OBJ_ROOT=.</tt>" option enabled in the
245 <tt>Makefile.config</tt> file, most source directories will contain two
246 directories, <tt>Depend</tt> and <tt>Debug</tt>. The <tt>Depend</tt>
247 directory contains automatically generated dependance files which are used
248 during compilation to make sure that source files get rebuilt if a header
249 file they use is modified. The <tt>Debug</tt> directory holds the object
250 files, library files, and executables that are used for building a debug
251 enabled build. The <tt>Release</tt> directory is created to hold the same
252 files when the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>,
253 causing an optimized built to be performed.<p>
254
255
256 <!------------------------------------------------------------------------->
257 <h3><a name="include"><tt>llvm/include</tt></a></h3>
258 <!------------------------------------------------------------------------->
259
260 This directory contains public header files exported from the LLVM
261 library. The two main subdirectories of this directory are:<p>
262
John Criswell8df90e02003-06-11 20:46:40 +0000[diff] [blame]263 <ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]264 <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
265 specific header files. This directory also has subdirectories for
266 different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
267 <tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...
268
269 <li><tt>llvm/include/Support</tt> - This directory contains generic
270 support libraries that are independant of LLVM, but are used by LLVM.
271 For example, header files for some C++ STL utilities and a Command Line
272 option processing library are located here.
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame]273 </ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]274
275 <!------------------------------------------------------------------------->
276 <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
277 <!------------------------------------------------------------------------->
278
279 This directory contains most source files of LLVM system. In LLVM, almost
280 all code exists in libraries, making it very easy to share code among the
281 different <a href="#tools">tools</a>.<p>
282
283 <dl compact>
284 <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
285 source files that implement core classes like Instruction and BasicBlock.
286
287 <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
288 for the LLVM assembly language parser library.
289
290 <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
291 and write LLVM bytecode.
292
293 <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
294 converter.
295
296 <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
297 different program analyses, such as Dominator Information, Call Graphs,
298 Induction Variables, Interval Identification, Natural Loop Identification,
299 etc...
300
301 <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
302 code for the LLVM to LLVM program transformations, such as Aggressive Dead
303 Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
304 Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
305 others...
306
307 <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
308 describe various target architectures for code generation. For example,
309 the llvm/lib/Target/Sparc directory holds the Sparc machine
310 description.<br>
311
312 <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
313 of the code generator: Instruction Selector, Instruction Scheduling, and
314 Register Allocation.
315
316 <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
317 to the runtime reoptimizer framework that is currently under development.
318
319 <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
320 that corresponds to the header files located in
321 <tt>llvm/include/Support/</tt>.
322 </dl>
323
324 <!------------------------------------------------------------------------->
325 <h3><a name="test"><tt>llvm/test</tt></a></h3>
326 <!------------------------------------------------------------------------->
327
328 <p>This directory contains regression tests and source code that is used to
329 test the LLVM infrastructure...</p>
330
331 <!------------------------------------------------------------------------->
332 <h3><a name="tools"><tt>llvm/tools</tt></a></h3>
333 <!------------------------------------------------------------------------->
334
335 <p>The <b>tools</b> directory contains the executables built out of the
336 libraries above, which form the main part of the user interface. You can
337 always get help for a tool by typing <tt>tool_name --help</tt>. The
338 following is a brief introduction to the most important tools.</p>
339
340 <dl compact>
341 <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
342 LLVM assembly to LLVM bytecode.<p>
343
344 <dt><tt><b>dis</b></tt><dd>The disassembler transforms the LLVM bytecode
345 to human readable LLVM assembly. Additionally it can convert LLVM
346 bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
347
348 <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
349 can directly execute LLVM bytecode (although very slowly...). In addition
350 to a simple intepreter, <tt>lli</tt> is also has debugger and tracing
351 modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
352 command line, respectively).<p>
353
354 <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
355 which translates LLVM bytecode to a SPARC assembly file.<p>
356
357 <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
358 that has been retargeted to emit LLVM code as the machine code output. It
359 works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
360 -o</tt> options that are typically used. The source code for the
361 <tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
362 because it is quite large and not very interesting.<p>
363
364 <ol>
365 <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
366 <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler. This
367 tool actually assembles LLVM assembly to LLVM bytecode,
368 performs a variety of optimizations,
369 and outputs LLVM bytecode. Thus when you invoke <tt>llvmgcc -c x.c -o
370 x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
371 <tt>x.o</tt> file (which is an LLVM bytecode file that can be
372 disassembled or manipulated just like any other bytecode file). The
373 command line interface to <tt>gccas</tt> is designed to be as close as
374 possible to the <b>system</b> '<tt>as</tt>' utility so that the gcc
375 frontend itself did not have to be modified to interface to a "wierd"
376 assembler.<p>
377
378 <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several LLVM
379 bytecode files into one bytecode file and does some optimization. It is
380 the linker invoked by the gcc frontend when multiple .o files need to be
381 linked together. Like <tt>gccas</tt> the command line interface of
382 <tt>gccld</tt> is designed to match the system linker, to aid
383 interfacing with the GCC frontend.<p>
384 </ol>
385
386 <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
387 series of LLVM to LLVM transformations (which are specified on the command
388 line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
389 command is a good way to get a list of the program transformations
390 available in LLVM.<p>
391
392
393 <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
394 analysis on an input LLVM bytecode file and print out the results. It is
395 primarily useful for debugging analyses, or familiarizing yourself with
396 what an analysis does.<p>
397
398 </dl>
399
400 <!--=====================================================================-->
401 <h2><a name="tutorial">An example using the LLVM tool chain</h2>
402 <!--=====================================================================-->
403
404 <ol>
405 <li>First, create a simple C file, name it 'hello.c':
406 <pre>
407 #include &lt;stdio.h&gt;
408 int main() {
409 printf("hello world\n");
410 return 0;
411 }
412 </pre>
413
414 <li>Next, compile the C file into a LLVM bytecode file:<p>
415
416 <tt>% llvmgcc hello.c -o hello</tt><p>
417
418 This will create two result files: <tt>hello</tt> and
419 <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
420 corresponds the the compiled program and the library facilities that it
421 required. <tt>hello</tt> is a simple shell script that runs the bytecode
422 file with <tt>lli</tt>, making the result directly executable.<p>
423
424 <li>Run the program. To make sure the program ran, execute one of the
425 following commands:<p>
John Criswell8df90e02003-06-11 20:46:40 +0000[diff] [blame]426
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]427 <tt>% ./hello</tt><p>
428
429 or<p>
430
431 <tt>% lli hello.bc</tt><p>
432
433 <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
434 code:<p>
435
436 <tt>% dis < hello.bc | less</tt><p>
437
438 <li>Compile the program to native Sparc assembly using the code
439 generator:<p>
440
441 <tt>% llc hello.bc -o hello.s</tt><p>
442
443 <li>Assemble the native sparc assemble file into a program:<p>
444
445 <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>
446
447 <li>Execute the native sparc program:<p>
448
449 <tt>% ./hello.sparc</tt><p>
450
451 </ol>
452
453
454 <!--=====================================================================-->
455 <h2><a name="links">Links</a></h2>
456 <!--=====================================================================-->
457
458 <p>This document is just an <b>introduction</b> to how to use LLVM to do
459 some simple things... there are many more interesting and complicated things
460 that you can do that aren't documented here (but we'll gladly accept a patch
461 if you want to write something up!). For more information about LLVM, check
462 out:</p>
463
464 <ul>
465 <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
466 <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
467 </ul>
468
469 <hr>
470
471 If you have any questions or run into any snags (or you have any
472 additions...), please send an email to
473 <a href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
474
475 <!-- Created: Mon Jul 1 02:29:02 CDT 2002 -->
476 <!-- hhmts start -->
477Last modified: Tue Jun 3 22:06:43 CDT 2003
478<!-- hhmts end -->
479 </body>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]480</html>