Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 7fe7f817e9e16c4773f5a4e3ba4c6144674d218e / . / docs / GettingStarted.html
blob: c3c34d3bcbdb5a6ef6a258c01dac00dcb5a1b591 [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
7 <body>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]8 <h1>Getting Started with the LLVM System</h1>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]9 <ul>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]10 <li><a href="#quickstart">Getting started with LLVM</a>
11 <ol>
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>
15 </ol>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]16 <li><a href="#layout">Program layout</a>
17 <ol>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]18 <li><a href="#cvsdir">CVS directories</a>
19 <li><a href="#dd">Depend, Debug, &amp; Release directories</a></li>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]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>
24 </ol>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]25 <li><a href="#tutorial">An example using the LLVM tool chain</a>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]26 <li><a href="#links">Links</a>
27 </ul>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]28
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]29
30
31 <!--=====================================================================-->
32 <h2><a name="quickstart">Getting Started with LLVM</a></h2>
33 <!--=====================================================================-->
34
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>
40
41
42 <!------------------------------------------------------------------------->
43 <h3><a name="tools">Checkout LLVM from CVS</a></h3>
44 <!------------------------------------------------------------------------->
45
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>
48
49 <p><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout llvm</tt></p>
50
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>
53
54
55 <!------------------------------------------------------------------------->
56 <h3><a name="tools">Set up your environment</a></h3>
57 <!------------------------------------------------------------------------->
58
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):
64
65 <pre>
66 # Make the C frontend easy to use...
67 alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
68
69 # Make the LLVM tools easy to use...
70 setenv PATH ~/llvm/tools/Debug:${PATH}
71 </pre>
72
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>
78
79
80
81 <!------------------------------------------------------------------------->
82 <h3><a name="compile">Compiling the Source Code</a></h3>
83 <!------------------------------------------------------------------------->
84
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>
93
94
95 <!--=====================================================================-->
96 <h2><a name="layout">Program Layout</a></h2>
97 <!--=====================================================================-->
98
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>
103
104
105 <!------------------------------------------------------------------------->
106 <h3><a name="cvsdir">CVS directories</a></h3>
107 <!------------------------------------------------------------------------->
108
109 Every directory checked out of CVS will contain a CVS directory, for the
110 most part these can just be ignored.
111
112
113 <!------------------------------------------------------------------------->
114 <h3><a name="ddr">Depend, Debug, &amp; Release directories</a></h3>
115 <!------------------------------------------------------------------------->
116
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.
125
126
127 <!------------------------------------------------------------------------->
128 <h3><a name="include">llvm/include</a></h3>
129 <!------------------------------------------------------------------------->
130
131 This directory contains public header files exported from the LLVM
132 library. The two main subdirectories of this directory are:
133
134 <ol>
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...
139
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
143 library.
144 </ol>
145
146 <!------------------------------------------------------------------------->
147 <h3><a name="lib">llvm/lib</a></h3>
148 <!------------------------------------------------------------------------->
149
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>
153
154 <dl compact>
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.
157
158 <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
159 for the LLVM assembly language parser library.
160
161 <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
162 and write LLVM bytecode.
163
164 <dt><tt>llvm/lib/CWrite/</tt><dd> This directory implements the LLVM to C
165 converter.
166
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,
170 etc...
171
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
176 others...
177
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
181 description.<br>
182
183 <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
184 of the code generator: Instruction Selector, Instruction Scheduling, and
185 Register Allocation.
186
187 <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
188 to the runtime reoptimizer framework that is currently under development.
189
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>.
193 </dl>
194
195 <!------------------------------------------------------------------------->
196 <h3><a name="test">llvm/test</a></h3>
197 <!------------------------------------------------------------------------->
198
199 <p>This directory contains regression tests and source code that is used to
200 test the LLVM infrastructure...</p>
201
202 <!------------------------------------------------------------------------->
203 <h3><a name="tools">llvm/tools</a></h3>
204 <!------------------------------------------------------------------------->
205
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>
210
211 <dl compact>
212 <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
213 llvm assembly to llvm bytecode.<p>
214
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>
218
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>
224
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>
227
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>
234
235 <ol>
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"
246 assembler.<p>
247
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>
254 </ol>
255
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>
261
262
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>
267
268 </dl>
269
270 <!--=====================================================================-->
271 <h2><a name="tutorial">An example using the LLVM tool chain</h2>
272 <!--=====================================================================-->
273
274 <ol>
275 <li>First, create a simple C file, name it 'hello.c':
276 <pre>
277 #include &lt;stdio.h&gt;
278 int main() {
279 printf("hello world\n");
280 return 0;
281 }
282 </pre>
283
284 <li>Next, compile the C file into a LLVM bytecode file:<p>
285
286 <tt>% llvmgcc hello.c -o hello</tt><p>
287
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>
293
294 <li>Run the program. To make sure the program ran, execute one of the
295 following commands:<p>
296
297 <tt>% ./hello</tt><p>
298
299 or<p>
300
301 <tt>% lli hello.bc</tt><p>
302
303 <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
304 code:<p>
305
306 <tt>% dis < hello.bc | less</tt><p>
307
308 <li>Compile the program to native Sparc assembly using the code
309 generator:<p>
310
311 <tt>% llc hello.bc -o hello.s</tt><p>
312
313 <li>Assemble the native sparc assemble file into a program:<p>
314
315 <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>
316
317 <li>Execute the native sparc program:<p>
318
319 <tt>% ./hello.sparc</tt><p>
320
321 </ol>
322
323
324 <!--=====================================================================-->
325 <h2><a name="links">Links</a></h2>
326 <!--=====================================================================-->
327
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
332 out:</p>
333
334 <ul>
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>
337 </ul>
338
339 <hr>
340
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>
345
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]346 <!-- Created: Mon Jul 1 02:29:02 CDT 2002 -->
347 <!-- hhmts start -->
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame^]348Last modified: Wed Jul 24 14:43:12 CDT 2002
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]349<!-- hhmts end -->
350 </body>
351</html>