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