1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>Getting Started with LLVM System</title>
8 <h1>Getting Started with the LLVM System</h1>
10 <li><a href="#quickstart">Getting started with LLVM</a>
12 <li><a href="#cvs">Checkout LLVM from CVS</a>
13 <li><a href="#environment">Set up your environment</a>
14 <li><a href="#compile">Compiling the Source Code</a>
16 <li><a href="#layout">Program layout</a>
18 <li><a href="#cvsdir">CVS directories</a>
19 <li><a href="#dd">Depend, Debug, & Release directories</a></li>
20 <li><a href="#include">llvm/include</a>
21 <li><a href="#lib">llvm/lib</a>
22 <li><a href="#test">llvm/test</a>
23 <li><a href="#tools">llvm/tools</a>
25 <li><a href="#tutorial">An example using the LLVM tool chain</a>
26 <li><a href="#links">Links</a>
31 <!--=====================================================================-->
32 <h2><a name="quickstart">Getting Started with LLVM</a></h2>
33 <!--=====================================================================-->
35 <p>This guide is meant to get you up and running with LLVM as quickly as
36 possible. Once you get the basic system running you can choose an area to
37 dive into and learn more about. If you get stuck or something is missing
38 from this document, please email <a
39 href="mailto:sabre@nondot.org">Chris</a>.</p>
42 <!------------------------------------------------------------------------->
43 <h3><a name="tools">Checkout LLVM from CVS</a></h3>
44 <!------------------------------------------------------------------------->
46 <p>First step is to get the actual source code. To do this, all you need to
47 do is check it out from CVS. From your home directory, just enter:</p>
49 <p><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout llvm</tt></p>
51 <p>This will create an '<tt>llvm</tt>' directory in your home directory and fully
52 populate it with the source code for LLVM.</p>
55 <!------------------------------------------------------------------------->
56 <h3><a name="tools">Set up your environment</a></h3>
57 <!------------------------------------------------------------------------->
59 <p>Now that you have the source code available, you should set up your
60 environment to be able to use the LLVM tools (once compiled) with as little
61 hassle as possible. To do this, we recommend that you add the following
62 lines to your <tt>.cshrc</tt> (or the corresponding lines to your
63 <tt>.profile</tt> if you use a bourne shell derivative):
66 # Make the C frontend easy to use...
67 alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
69 # Make the LLVM tools easy to use...
70 setenv PATH ~/llvm/tools/Debug:${PATH}
73 <p>The C compiler is not included in the CVS tree you just checked out, so
74 we just point to the cannonical location, and access it with the
75 <tt>llvmgcc</tt> command. The rest of the <a href="#tools">LLVM tools</a>
76 will be built into the llvm/tools/Debug directory inside of the sourcebase.
77 Adding them to your path will make it much easier to use them.</p>
81 <!------------------------------------------------------------------------->
82 <h3><a name="compile">Compiling the Source Code</a></h3>
83 <!------------------------------------------------------------------------->
85 <p>Every directory in the LLVM source tree includes a Makefile to build it,
86 and any subdirectories that it contains. These makefiles require that you
87 use <tt>gmake</tt>, instead of <tt>make</tt> to build them, but can
88 otherwise be used freely. To build the entire LLVM system, just enter the
89 top level <tt>llvm</tt> directory and type <tt>gmake</tt>. A few minutes
90 later you will hopefully have a freshly compiled toolchain waiting for you
91 in <tt>llvm/tools/Debug</tt>. If you want to look at the libraries that
92 were compiled, look in <tt>llvm/lib/Debug</tt>.</p>
95 <!--=====================================================================-->
96 <h2><a name="layout">Program Layout</a></h2>
97 <!--=====================================================================-->
99 <p>One useful source of infomation about the LLVM sourcebase is the LLVM
100 doxygen documentation, available at <tt><a
101 href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>. The
102 following is a brief introduction to code layout:</p>
105 <!------------------------------------------------------------------------->
106 <h3><a name="cvsdir">CVS directories</a></h3>
107 <!------------------------------------------------------------------------->
109 Every directory checked out of CVS will contain a CVS directory, for the
110 most part these can just be ignored.
113 <!------------------------------------------------------------------------->
114 <h3><a name="ddr">Depend, Debug, & Release directories</a></h3>
115 <!------------------------------------------------------------------------->
117 Most source directories contain two directories, Depend and Debug. The
118 Depend directory contains automatically generated dependance files which are
119 used during compilation to make sure that source files get rebuilt if a
120 header file they use is modified. The Debug directory holds the object
121 files, library files and executables that are used for building a debug
122 enabled build. The Release directory is created to hold the same files when
123 the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>, causing an
124 optimized built to be performed.
127 <!------------------------------------------------------------------------->
128 <h3><a name="include">llvm/include</a></h3>
129 <!------------------------------------------------------------------------->
131 This directory contains public header files exported from the LLVM
132 library. The two main subdirectories of this directory are:
135 <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
136 specific header files. This directory also has subdirectories for
137 different portions of llvm: <tt>Analysis</tt>, <tt>CodeGen</tt>,
138 <tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...
140 <li><tt>llvm/include/Support</tt> - This directory contains generic
141 support libraries that are independant of LLVM, but are used by LLVM.
142 For example, some C++ STL utilities and a Command Line option processing
146 <!------------------------------------------------------------------------->
147 <h3><a name="lib">llvm/lib</a></h3>
148 <!------------------------------------------------------------------------->
150 This directory contains most source files of LLVM system. In LLVM almost all
151 code exists in libraries, making it very easy to share code among the
152 different <a href="#tools">tools</a>.<p>
155 <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
156 source files that implement core classes like Instruction and BasicBlock.
158 <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
159 for the LLVM assembly language parser library.
161 <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
162 and write LLVM bytecode.
164 <dt><tt>llvm/lib/CWrite/</tt><dd> This directory implements the LLVM to C
167 <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
168 different program analyses, such as Dominator Information, Call Graphs,
169 Induction Variables, Interval Identification, Natural Loop Identification,
172 <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
173 code for the LLVM to LLVM program transformations, such as Aggressive Dead
174 Code Elimination, Sparse Conditional Constant Propogation, Inlining, Loop
175 Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
178 <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
179 describe various target architectures for code generation. For example,
180 the llvm/lib/Target/Sparc directory holds the Sparc machine
183 <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
184 of the code generator: Instruction Selector, Instruction Scheduling, and
187 <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
188 to the runtime reoptimizer framework that is currently under development.
190 <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
191 that corresponds to the header files located in
192 <tt>llvm/include/Support/</tt>.
195 <!------------------------------------------------------------------------->
196 <h3><a name="test">llvm/test</a></h3>
197 <!------------------------------------------------------------------------->
199 <p>This directory contains regression tests and source code that is used to
200 test the LLVM infrastructure...</p>
202 <!------------------------------------------------------------------------->
203 <h3><a name="tools">llvm/tools</a></h3>
204 <!------------------------------------------------------------------------->
206 <p>The <b>tools</b> directory contains the executables built out of the
207 libraries above, which form the main part of the user interface. You can
208 always get help for a tool by typing <tt>tool_name --help</tt>. The
209 following is a brief introduction to the most important tools.</p>
212 <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
213 llvm assembly to llvm bytecode.<p>
215 <dt><tt><b>dis</b></tt><dd>The disassembler transforms the llvm bytecode
216 to human readable llvm assembly. Additionally it can convert LLVM
217 bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
219 <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
220 can directly execute LLVM bytecode (although very slowly...). In addition
221 to a simple intepreter, <tt>lli</tt> is also has debugger and tracing
222 modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
223 command line, respectively).<p>
225 <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
226 which translates LLVM bytecode to a SPARC assembly file.<p>
228 <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
229 that has been retargeted to emit LLVM code as the machine code output. It
230 works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
231 -o</tt> options that are typically used. The source code for the
232 <tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
233 because it is quite large and not very interesting.<p>
236 <dt><tt><b>gccas</b></tt><dd> This took is invoked by the
237 <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler. This
238 tool actually assembles its input, performs a variety of optimizations,
239 and outputs LLVM bytecode. Thus when you invoke <tt>llvmgcc -c x.c -o
240 x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
241 <tt>x.o</tt> file (which is an LLVM bytecode file that can be
242 disassembled or manipulated just like any other bytecode file). The
243 command line interface to <tt>gccas</tt> is designed to be as close as
244 possible to the <b>system</b> <tt>as</tt> utility so that the gcc
245 frontend itself did not have to be modified to interface to a "wierd"
248 <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several llvm
249 bytecode files into one bytecode file and does some optimization. It is
250 the linker invoked by the gcc frontend when multiple .o files need to be
251 linked together. Like <tt>gccas</tt> the command line interface of
252 <tt>gccld</tt> is designed to match the system linker, to aid
253 interfacing with the GCC frontend.<p>
256 <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads llvm bytecode, applies a
257 series of LLVM to LLVM transformations (which are specified on the command
258 line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
259 command is a good way to get a list of the program transformations
260 available in LLVM.<p>
263 <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
264 analysis on an input LLVM bytecode file and print out the results. It is
265 primarily useful for debugging analyses, or familiarizing yourself with
266 what an analysis does.<p>
270 <!--=====================================================================-->
271 <h2><a name="tutorial">An example using the LLVM tool chain</h2>
272 <!--=====================================================================-->
275 <li>First, create a simple C file, name it 'hello.c':
277 #include <stdio.h>
279 printf("hello world\n");
284 <li>Next, compile the C file into a LLVM bytecode file:<p>
286 <tt>% llvmgcc hello.c -o hello</tt><p>
288 This will create two result files: <tt>hello</tt> and
289 <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
290 corresponds the the compiled program and the library facilities that it
291 required. <tt>hello</tt> is a simple shell script that runs the bytecode
292 file with <tt>lli</tt>, making the result directly executable.<p>
294 <li>Run the program. To make sure the program ran, execute one of the
295 following commands:<p>
297 <tt>% ./hello</tt><p>
301 <tt>% lli hello.bc</tt><p>
303 <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
306 <tt>% dis < hello.bc | less</tt><p>
308 <li>Compile the program to native Sparc assembly using the code
311 <tt>% llc hello.bc -o hello.s</tt><p>
313 <li>Assemble the native sparc assemble file into a program:<p>
315 <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>
317 <li>Execute the native sparc program:<p>
319 <tt>% ./hello.sparc</tt><p>
324 <!--=====================================================================-->
325 <h2><a name="links">Links</a></h2>
326 <!--=====================================================================-->
328 <p>This document is just an <b>introduction</b> to how to use LLVM to do
329 some simple things... there are many more interesting and complicated things
330 that you can do that aren't documented here (but we'll gladly accept a patch
331 if you want to write something up!). For more information about LLVM, check
335 <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
336 <li><a href="http://tank.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
341 If you have any questions or run into any snags (or you have any
342 additions...), please send an email to <a
343 href="mailto:sabre@nondot.org">Chris Lattner</a> or <a
344 href="mailto:gshi1@uiuc.edu">Guochun Shi</a>. <p>
346 <!-- Created: Mon Jul 1 02:29:02 CDT 2002 -->
348 Last modified: Wed Jul 24 14:43:12 CDT 2002