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