Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / d000e1dc2f08892aaa8c1bfd96f85f24b9d66cbb / . / docs / GettingStarted.html
blob: 849aa9735822c442c04bf8fb32db6c951f9edadd [file] [log] [blame]
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]3<html>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]4<head>
5 <title>Getting Started with LLVM System</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]9
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]10<div class="doc_title">
11 Getting Started with the LLVM System
12</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]13
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]14<ul>
15 <li><a href="#overview">Overview</a>
16 <li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
17 <li><a href="#requirements">Requirements</a>
Chris Lattner96768ea2003-02-14 04:22:13 +0000[diff] [blame]18 <ol>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]19 <li><a href="#hardware">Hardware</a>
20 <li><a href="#software">Software</a>
21 </ol></li>
John Criswell7a73b802003-06-30 21:59:07 +0000[diff] [blame]22
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]23 <li><a href="#starting">Getting Started with LLVM</a>
John Criswell0b459202003-07-08 20:35:59 +0000[diff] [blame]24 <ol>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]25 <li><a href="#terminology">Terminology and Notation</a>
26 <li><a href="#environment">Setting Up Your Environment</a>
27 <li><a href="#unpack">Unpacking the LLVM Archives</a>
28 <li><a href="#checkout">Checkout LLVM from CVS</a>
29 <li><a href="#installcf">Install the GCC Front End</a>
30 <li><a href="#config">Local LLVM Configuration</a>
31 <li><a href="#compile">Compiling the LLVM Suite Source Code</a>
32 <li><a href="#objfiles">The Location of LLVM Object Files</a>
33 </ol></li>
John Criswell0b459202003-07-08 20:35:59 +0000[diff] [blame]34
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]35 <li><a href="#layout">Program layout</a>
36 <ol>
37 <li><a href="#cvsdir"><tt>CVS</tt> directories</a>
38 <li><a href="#include"><tt>llvm/include</tt></a>
39 <li><a href="#lib"><tt>llvm/lib</tt></a>
40 <li><a href="#runtime"><tt>llvm/runtime</tt></a>
41 <li><a href="#test"><tt>llvm/test</tt></a>
42 <li><a href="#tools"><tt>llvm/tools</tt></a>
43 <li><a href="#utils"><tt>llvm/utils</tt></a>
44 </ol></li>
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]45
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]46 <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
47 <li><a href="#problems">Common Problems</a>
48 <li><a href="#links">Links</a>
49</ul>
50
51<p>By:
52 <a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>,
53 <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
54 <a href="mailto:criswell@uiuc.edu">John Criswell</a>,
55 <a href="http://misha.brukman.net">Misha Brukman</a>, and
56 <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>.</p>
57
58
59<!-- *********************************************************************** -->
60<div class="doc_section">
61 <a name="overview"><b>Overview</b></a>
62</div>
63<!-- *********************************************************************** -->
64
65<div class="doc_text">
66
67<p>Welcome to LLVM! In order to get started, you first need to know some
68basic information.</p>
69
70<p>First, LLVM comes in two pieces. The first piece is the LLVM suite. This
71contains all of the tools, libraries, and header files needed to use the low
72level virtual machine. It contains an assembler, disassembler, bytecode
73analyzer, and bytecode optimizer. It also contains a test suite that can be
74used to test the LLVM tools and the GCC front end.</p>
75
76<p>The second piece is the GCC front end. This component provides a version of
77GCC that compiles C and C++ code into LLVM bytecode. Currently, the GCC front
78end is a modified version of GCC 3.4 (we track the GCC 3.4 development). Once
79compiled into LLVM bytecode, a program can be manipulated with the LLVM tools
80from the LLVM suite.</p>
81
82</div>
83
84<!-- *********************************************************************** -->
85<div class="doc_section">
86 <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
87</div>
88<!-- *********************************************************************** -->
89
90<div class="doc_text">
91
92<p>Here's the short story for getting up and running quickly with LLVM:</p>
93
94<ol>
95 <li>Install the GCC front end:
96 <ol>
97 <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt>
98 <li><tt>gunzip --stdout cfrontend.<i>platform</i>.tar.gz | tar -xvf -</tt>
99 <li><b>Sparc Only:</b><br>
100 <tt>cd cfrontend/sparc<br>
101 ./fixheaders</tt>
102 </ol></li>
103
104 <li>Get the Source Code
105 <ul>
106 <li>With the distributed files:
107 <ol>
108 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
109 <li><tt>gunzip --stdout llvm.tar.gz | tar -xvf -</tt>
110 <li><tt>cd llvm</tt>
111 </ol></li>
112
113 <li>With anonymous CVS access:
114 <ol>
115 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
116 <li><tt>cvs -d
117 :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt></li>
118 <li>Hit the return key when prompted for the password.
119 <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
120 co llvm</tt></li>
121 <li><tt>cd llvm</tt></li>
122 </ol></li>
123 </ul></li>
124
125 <li>Configure the LLVM Build Environment
126 <ol>
127 <li>Change directory to where you want to store the LLVM object
128 files and run <tt>configure</tt> to configure the Makefiles and
129 header files for the default platform. Useful options include:
130 <ul>
131 <li><tt>--with-llvmgccdir=<i>directory</i></tt>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]132 <p>Specify the full pathname of where the LLVM GCC frontend is
133 installed.</p></li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]134 <li><tt>--enable-spec2000=<i>directory</i></tt>
135 <p>Enable the SPEC2000 benchmarks for testing. The SPEC2000
136 benchmarks should be available in
137 <tt><i>directory</i></tt>.</p></li>
138 </ul>
139 </ol></li>
140
141 <li>Build the LLVM Suite:
142 <ol>
143 <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
144 <li><tt>gmake -k |& tee gnumake.out
145 &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
146 </ol>
147
148</ol>
149
150<p>Consult the <a href="starting">Getting Started with LLVM</a> section for
151detailed information on configuring and compiling LLVM. See <a
152href="#environment">Setting Up Your Environment</a> for tips that simplify
153working with the GCC front end and LLVM tools. Go to <a href="#layout">Program
154Layout</a> to learn about the layout of the source code tree.</p>
155
156</div>
157
158<!-- *********************************************************************** -->
159<div class="doc_section">
160 <a name="requirements"><b>Requirements</b></a>
161</div>
162<!-- *********************************************************************** -->
163
164<div class="doc_text">
165
166<p>Before you begin to use the LLVM system, review the requirements given below.
167This may save you some trouble by knowing ahead of time what hardware and
168software you will need.</p>
169
170</div>
171
172<!-- ======================================================================= -->
173<div class="doc_subsection">
174 <a name="hardware"><b>Hardware</b></a>
175</div>
176
177<div class="doc_text">
178
179<p>LLVM is known to work on the following platforms:</p>
180
181<ul>
182
183 <li>Linux on x86 (Pentium and above)
184 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]185 <li>Approximately 918 MB of Free Disk Space
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]186 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]187 <li>Source code: 28 MB</li>
188 <li>Object code: 850 MB</li>
189 <li>GCC front end: 40 MB</li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]190 </ul></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]191 </ul>
192 </li>
193
194 <p></p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]195
196 <li>Solaris on SparcV9 (Ultrasparc)
197 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]198 <li>Approximately 1.52 GB of Free Disk Space
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]199 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]200 <li>Source code: 28 MB</li>
201 <li>Object code: 1470 MB</li>
202 <li>GCC front end: 50 MB</li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]203 </ul></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]204 </ul>
205 </li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]206
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]207 <p></p>
208
209 <li>FreeBSD on x86 (Pentium and above)
210 <ul>
211 <li>Approximately 918 MB of Free Disk Space
212 <ul>
213 <li>Source code: 28 MB</li>
214 <li>Object code: 850 MB</li>
215 <li>GCC front end: 40 MB</li>
216 </ul></li>
217 </ul>
218 </li>
219
220 <p></p>
221
222 <li>MacOS X on PowerPC
223 <ul>
224 <li>No native code generation
225 <li>Approximately 1.20 GB of Free Disk Space
226 <ul>
227 <li>Source code: 28 MB</li>
228 <li>Object code: 1160 MB</li>
229 <li>GCC front end: 40 MB</li>
230 </ul></li>
231 </ul>
232
233 </li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]234</ul>
235
236<p>The LLVM suite <i>may</i> compile on other platforms, but it is not
237guaranteed to do so. If compilation is successful, the LLVM utilities should be
238able to assemble, disassemble, analyze, and optimize LLVM bytecode. Code
239generation should work as well, although the generated native code may not work
240on your platform.</p>
241
242<p>The GCC front end is not very portable at the moment. If you want to get it
243to work on another platform, you can download a copy of the source and try to
244compile it on your platform.</p>
245
246</div>
247
248<!-- ======================================================================= -->
249<div class="doc_subsection">
250 <a name="software"><b>Software</b></a>
251</div>
252
253<div class="doc_text">
254
255<p>Compiling LLVM requires that you have several software packages
256installed:</p>
257
258<ul>
259 <li><a href="http://gcc.gnu.org">GCC 3.x with C and C++ language
260 support</a></li>
261
262 <li><a href="http://savannah.gnu.org/projects/make">GNU Make</a></li>
263
264 <li><a href="http://www.gnu.org/software/flex">Flex</a></li>
265
266 <li><a href="http://www.gnu.org/software/bison/bison.html">Bison</a></li>
267</ul>
268
269<p>There are some additional tools that you may want to have when working with
270LLVM:</p>
271
272<ul>
273 <li><A href="http://www.gnu.org/software/autoconf">GNU Autoconf</A>
274 <li><A href="http://savannah.gnu.org/projects/m4">GNU M4</A>
275
276 <p>If you want to make changes to the configure scripts, you will need GNU
277 autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 or
278 higher).</p></li>
279
280 <li><A href="http://www.codesourcery.com/qm/qmtest">QMTest</A></li>
281 <li><A href="http://www.python.org">Python</A>
282
283 <p>These are needed to use the LLVM test suite.</p></li>
284
285</ul>
286
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]287<p>The remainder of this guide is meant to get you up and running with
288LLVM and to give you some basic information about the LLVM environment.
289A <a href="#starting">complete guide to installation</a> is provided in the
290next section.</p>
291
292<p>The later sections of this guide describe the <a
293href="#layout">general layout</a> of the the LLVM source tree, a <a
294href="#tutorial">simple example</a> using the LLVM tool chain, and <a
295href="#links">links</a> to find more information about LLVM or to get
296help via e-mail.</p>
297
298</div>
299
300<!-- *********************************************************************** -->
301<div class="doc_section">
302 <a name="starting"><b>Getting Started with LLVM</b></a>
303</div>
304<!-- *********************************************************************** -->
305
306<!-- ======================================================================= -->
307<div class="doc_subsection">
308 <a name="terminology">Terminology and Notation</a>
309</div>
310
311<div class="doc_text">
312
313<p>Throughout this manual, the following names are used to denote paths
314specific to the local system and working environment. <i>These are not
315environment variables you need to set but just strings used in the rest
316of this document below</i>. In any of the examples below, simply replace
317each of these names with the appropriate pathname on your local system.
318All these paths are absolute:</p>
319
320<dl compact>
321 <dt>SRC_ROOT
322 <dd>
323 This is the top level directory of the LLVM source tree.
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]324 <p>
325
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]326 <dt>OBJ_ROOT
327 <dd>
328 This is the top level directory of the LLVM object tree (i.e. the
329 tree where object files and compiled programs will be placed. It
330 can be the same as SRC_ROOT).
331 <p>
332
333 <dt>LLVMGCCDIR
334 <dd>
335 This is the where the LLVM GCC Front End is installed.
336 <p>
337 For the pre-built GCC front end binaries, the LLVMGCCDIR is
338 <tt>cfrontend/<i>platform</i>/llvm-gcc</tt>.
339</dl>
340
341</div>
342
343<!-- ======================================================================= -->
344<div class="doc_subsection">
345 <a name="environment">Setting Up Your Environment</a>
346</div>
347
348<div class="doc_text">
349
350<p>
351In order to compile and use LLVM, you will need to set some environment
352variables. There are also some shell aliases which you may find useful.
353You can set these on the command line, or better yet, set them in your
354<tt>.cshrc</tt> or <tt>.profile</tt>.
355
356<dl compact>
357 <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt><i>LLVMGCCDIR</i>/bytecode-libs</tt>
358 <dd>
359 This environment variable helps the LLVM GCC front end find bytecode
360 libraries that it will need for compilation.
361 <p>
362
363 <dt>alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/gcc</tt>
364 <dt>alias llvmg++ <i>LLVMGCCDIR</i><tt>/bin/g++</tt>
365 <dd>
366 This alias allows you to use the LLVM C and C++ front ends without putting
367 them in your <tt>PATH</tt> or typing in their complete pathnames.
368</dl>
369
370</div>
371
372<!-- ======================================================================= -->
373<div class="doc_subsection">
374 <a name="unpack">Unpacking the LLVM Archives</a></h3>
375</div>
376
377<div class="doc_text">
378
379<p>
380If you have the LLVM distribution, you will need to unpack it before you
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]381can begin to compile it. LLVM is distributed as a set of two files: the LLVM
382suite and the LLVM GCC front end compiled for your platform. Each
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]383file is a TAR archive that is compressed with the gzip program.
384</p>
385
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]386<p> The files are as follows:
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]387<dl compact>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]388 <dt>llvm-1.1.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]389 <dd>This is the source code to the LLVM suite.
390 <p>
391
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]392 <dt>cfrontend-1.1.sparc-sun-solaris2.8.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]393 <dd>This is the binary release of the GCC front end for Solaris/Sparc.
394 <p>
395
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]396 <dt>cfrontend-1.1.i686-redhat-linux-gnu.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]397 <dd>This is the binary release of the GCC front end for Linux/x86.
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]398 <p>
399
400 <dt>cfrontend-1.1.i386-unknown-freebsd5.1.tar.gz
401 <dd>This is the binary release of the GCC front end for FreeBSD/x86.
402 <p>
403
404 <dt>cfrontend-1.1.powerpc-apple-darwin7.0.0.tar.gz
405 <dd>This is the binary release of the GCC front end for MacOS X/PPC.
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]406</dl>
407
408</div>
409
410<!-- ======================================================================= -->
411<div class="doc_subsection">
412 <a name="checkout">Checkout LLVM from CVS</a></h3>
413</div>
414
415<div class="doc_text">
416
417<p>If you have access to our CVS repository, you can get a fresh copy of
418the entire source code. All you need to do is check it out from CVS as
419follows:</p>
420
421<ul>
422<li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
423 <li><tt>cvs -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt>
424 <li>Hit the return key when prompted for the password.
425 <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
426 llvm</tt>
427</ul>
428
429<p>This will create an '<tt>llvm</tt>' directory in the current
430directory and fully populate it with the LLVM source code, Makefiles,
431test directories, and local copies of documentation files.</p>
432
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]433<p>
434If you want to get a specific release (as opposed to the most recent revision),
435you can specify a label. The following releases have the following label:
436<ul>
437 <li>
438 Release 1.1: <b>RELEASE_11</b>
439 </li>
440
441 <li>
442 Release 1.0: <b>RELEASE_1</b>
443 </li>
444</ul>
445</p>
446
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]447<p>Note that the GCC front end is not included in the CVS repository. You
448should have downloaded the binary distribution for your platform.</p>
449
450</div>
451
452<!-- ======================================================================= -->
453<div class="doc_subsection">
454 <a name="installcf">Install the GCC Front End</a></h3>
455</div>
456
457<div class="doc_text">
458
459<p>Before configuring and compiling the LLVM suite, you need to extract the LLVM
460GCC front end from the binary distribution. It is used for building the
461bytecode libraries later used by the GCC front end for linking programs, and its
462location must be specified when the LLVM suite is configured.</p>
463
464<p>To install the GCC front end, do the following:</p>
465
466<ol>
467 <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]468 <li><tt>gunzip --stdout cfrontend-<i>version</i>.<i>platform</i>.tar.gz | tar -xvf
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]469 -</tt></li>
470</ol>
471
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]472<p>If you are using Solaris/Sparc or MacOS X/PPC, you will need to fix the
473header files:</p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]474
475<p><tt>cd cfrontend/sparc<br>
476 ./fixheaders</tt></p>
477
478<p>The binary versions of the GCC front end may not suit all of your needs. For
479example, the binary distribution may include an old version of a system header
480file, not "fix" a header file that needs to be fixed for GCC, or it may be
481linked with libraries not available on your system.</p>
482
483<p>In cases like these, you may want to try <a
484href="CFEBuildInstrs.html">building the GCC front end from source.</a> This is
485not for the faint of heart, so be forewarned.</p>
486
487</div>
488
489<!-- ======================================================================= -->
490<div class="doc_subsection">
491 <a name="config">Local LLVM Configuration</a>
492</div>
493
494<div class="doc_text">
495
496<p>Once checked out from the CVS repository, the LLVM suite source code must be
497configured via the <tt>configure</tt> script. This script sets variables in
498<tt>llvm/Makefile.config</tt> and <tt>llvm/include/Config/config.h</tt>. It
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]499also populates <i>OBJ_ROOT</i> with the Makefiles needed to begin building
500LLVM.</p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]501
502<p>The following environment variables are used by the <tt>configure</tt>
503script to configure the build system:</p>
504
505<table border=1>
506 <tr>
507 <th>Variable</th>
508 <th>Purpose</th>
509 </tr>
510
511 <tr>
512 <td>CC</td>
513 <td>Tells <tt>configure</tt> which C compiler to use. By default,
514 <tt>configure</tt> will look for the first GCC C compiler in
515 <tt>PATH</tt>. Use this variable to override
516 <tt>configure</tt>'s default behavior.</td>
517 </tr>
518
519 <tr>
520 <td>CXX</td>
521 <td>Tells <tt>configure</tt> which C++ compiler to use. By default,
522 <tt>configure</tt> will look for the first GCC C++ compiler in
523 <tt>PATH</tt>. Use this variable to override
524 <tt>configure</tt>'s default behavior.</td>
525 </tr>
526</table>
527
528<p>The following options can be used to set or enable LLVM specific options:</p>
529
530<dl compact>
531 <dt><i>--with-llvmgccdir=LLVMGCCDIR</i>
532 <dd>
533 Path to the location where the LLVM C front end binaries and
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]534 associated libraries were installed. This must be specified as an
535 absolute pathname.
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]536 <p>
537 <dt><i>--enable-optimized</i>
538 <dd>
539 Enables optimized compilation by default (debugging symbols are removed
540 and GCC optimization flags are enabled). The default is to use an
541 unoptimized build (also known as a debug build).
542 <p>
543 <dt><i>--enable-jit</i>
544 <dd>
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]545 Compile the Just In Time (JIT) compiler functionality. This is not
546 available
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]547 on all platforms. The default is dependent on platform, so it is best
548 to explicitly enable it if you want it.
549 <p>
550 <dt><i>--enable-spec2000</i>
551 <dt><i>--enable-spec2000=&lt;<tt>directory</tt>&gt;</i>
552 <dd>
553 Enable the use of SPEC2000 when testing LLVM. This is disabled by default
554 (unless <tt>configure</tt> finds SPEC2000 installed). By specifying
555 <tt>directory</tt>, you can tell configure where to find the SPEC2000
556 benchmarks. If <tt>directory</tt> is left unspecified, <tt>configure</tt>
557 uses the default value
558 <tt>/home/vadve/shared/benchmarks/speccpu2000/benchspec</tt>.
559</dl>
560
561<p>To configure LLVM, follow these steps:</p>
562
563<ol>
564 <li>Change directory into the object root directory:
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]565 <br>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]566 <tt>cd <i>OBJ_ROOT</i></tt>
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]567 <p>
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]568
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]569 <li>Run the <tt>configure</tt> script located in the LLVM source tree:
570 <br>
571 <tt><i>SRC_ROOT</i>/configure</tt>
John Criswell0f6d7c02003-10-27 18:18:16 +0000[diff] [blame]572 <p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]573</ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]574
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]575<p>In addition to running <tt>configure</tt>, you must set the
576<tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
577This environment variable is used to locate "system" libraries like
578"<tt>-lc</tt>" and "<tt>-lm</tt>" when linking. This variable should be set to
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]579the absolute path of the <tt>bytecode-libs</tt> subdirectory of the GCC front
580end, or <i>LLVMGCCDIR</i>/<tt>bytecode-libs</tt>. For example, one might set
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]581<tt>LLVM_LIB_SEARCH_PATH</tt> to
John Criswelld000e1d2003-12-18 16:43:17 +0000[diff] [blame^]582<tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the x86
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]583version of the GCC front end on our research machines.</p>
John Criswell7a73b802003-06-30 21:59:07 +0000[diff] [blame]584
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]585</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]586
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]587<!-- ======================================================================= -->
588<div class="doc_subsection">
589 <a name="compile">Compiling the LLVM Suite Source Code</a>
590</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]591
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]592<div class="doc_text">
John Criswell0b459202003-07-08 20:35:59 +0000[diff] [blame]593
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]594<p>Once you have configured LLVM, you can build it. There are three types of
595builds:</p>
John Criswell0b459202003-07-08 20:35:59 +0000[diff] [blame]596
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]597<dl compact>
598 <dt>Debug Builds
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]599 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]600 These builds are the default when one types <tt>gmake</tt> (unless the
601 <tt>--enable-optimized</tt> option was used during configuration). The
602 build system will compile the tools and libraries with debugging
603 information.
604 <p>
605
606 <dt>Release (Optimized) Builds
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]607 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]608 These builds are enabled with the <tt>--enable-optimized</tt> option to
609 <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
610 <tt>gmake</tt> command line. For these builds, the build system will
611 compile the tools and libraries with GCC optimizations enabled and strip
612 debugging information from the libraries and executables it generates.
613 <p>
614
615 <dt>Profile Builds
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]616 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]617 These builds are for use with profiling. They compile profiling
618 information into the code for use with programs like <tt>gprof</tt>.
619 Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
620 on the <tt>gmake</tt> command line.
621</dl>
John Criswell7a73b802003-06-30 21:59:07 +0000[diff] [blame]622
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]623<p>Once you have LLVM configured, you can build it by entering the
624<i>OBJ_ROOT</i> directory and issuing the following command:</p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]625
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]626<p><tt>gmake</tt></p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]627
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]628<p>If you have multiple processors in your machine, you may wish to use some of
629the parallel build options provided by GNU Make. For example, you could use the
630command:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]631
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]632<p><tt>gmake -j2</tt></p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]633
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]634<p>There are several special targets which are useful when working with the LLVM
635source code:</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]636
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]637<dl compact>
638 <dt><tt>gmake clean</tt>
639 <dd>
640 Removes all files generated by the build. This includes object files,
641 generated C/C++ files, libraries, and executables.
642 <p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]643
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]644 <dt><tt>gmake distclean</tt>
645 <dd>
646 Removes everything that <tt>gmake clean</tt> does, but also removes
647 files generated by <tt>configure</tt>. It attempts to return the
648 source tree to the original state in which it was shipped.
649 <p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]650
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]651 <dt><tt>gmake install</tt>
652 <dd>
653 Installs LLVM files into the proper location. For the most part,
654 this does nothing, but it does install bytecode libraries into the
655 GCC front end's bytecode library directory. If you need to update
656 your bytecode libraries, this is the target to use once you've built
657 them.
658 <p>
659</dl>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]660
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]661<p>It is also possible to override default values from <tt>configure</tt> by
662declaring variables on the command line. The following are some examples:</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]663
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]664<dl compact>
665 <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
666 <dd>
667 Perform a Release (Optimized) build.
668 <p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]669
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]670 <dt><tt>gmake ENABLE_PROFILING=1</tt>
671 <dd>
672 Perform a Profiling build.
673 <p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]674
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]675 <dt><tt>gmake VERBOSE=1</tt>
676 <dd>
677 Print what <tt>gmake</tt> is doing on standard output.
678 <p>
679</dl>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]680
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]681<p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
682it and any subdirectories that it contains. Entering any directory inside the
683LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
684that directory that is out of date.</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]685
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]686</div>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]687
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]688<!-- ======================================================================= -->
689<div class="doc_subsection">
690 <a name="objfiles">The Location of LLVM Object Files</a>
691</div>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]692
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]693<div class="doc_text">
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]694
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]695<p>The LLVM build system is capable of sharing a single LLVM source tree among
696several LLVM builds. Hence, it is possible to build LLVM for several different
697platforms or configurations using the same source tree.</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]698
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]699<p>This is accomplished in the typical autoconf manner:</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]700
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]701<ul>
702 <li><p>Change directory to where the LLVM object files should live:</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]703
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]704 <p><tt>cd <i>OBJ_ROOT</i></tt></p></li>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]705
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]706 <li><p>Run the <tt>configure</tt> script found in the LLVM source
707 directory:</p>
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]708
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]709 <p><tt><i>SRC_ROOT</i>/configure</tt></p></li>
710</ul>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]711
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]712<p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
713named after the build type:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]714
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]715<dl compact>
716 <dt>Debug Builds
717 <dd>
718 <dl compact>
719 <dt>Tools
720 <dd><tt><i>OBJ_ROOT</i>/tools/Debug</tt>
721 <dt>Libraries
722 <dd><tt><i>OBJ_ROOT</i>/lib/Debug</tt>
723 </dl>
724 <p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]725
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]726 <dt>Release Builds
727 <dd>
728 <dl compact>
729 <dt>Tools
730 <dd><tt><i>OBJ_ROOT</i>/tools/Release</tt>
731 <dt>Libraries
732 <dd><tt><i>OBJ_ROOT</i>/lib/Release</tt>
733 </dl>
734 <p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]735
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]736 <dt>Profile Builds
737 <dd>
738 <dl compact>
739 <dt>Tools
740 <dd><tt><i>OBJ_ROOT</i>/tools/Profile</tt>
741 <dt>Libraries
742 <dd><tt><i>OBJ_ROOT</i>/lib/Profile</tt>
743 </dl>
744</dl>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]745
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]746</div>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000[diff] [blame]747
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]748<!-- *********************************************************************** -->
749<div class="doc_section">
750 <a name="layout"><b>Program Layout</b></a>
751</div>
752<!-- *********************************************************************** -->
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]753
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]754<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]755
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]756<p>One useful source of information about the LLVM source base is the LLVM <a
757href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
758href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>.
759The following is a brief introduction to code layout:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]760
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]761</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]762
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]763<!-- ======================================================================= -->
764<div class="doc_subsection">
765 <a name="cvsdir"><tt>CVS</tt> directories</a>
766</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]767
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]768<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]769
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]770<p>Every directory checked out of CVS will contain a <tt>CVS</tt> directory; for
771the most part these can just be ignored.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]772
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]773</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]774
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]775<!-- ======================================================================= -->
776<div class="doc_subsection">
777 <a name="include"><tt>llvm/include</tt></a>
778</div>
779
780<div class="doc_text">
781
782<p>This directory contains public header files exported from the LLVM
783library. The three main subdirectories of this directory are:</p>
784
785<ol>
786 <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
787 specific header files. This directory also has subdirectories for
788 different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
789 <tt>Target</tt>, <tt>Transforms</tt>, etc...</li>
790
791 <li><tt>llvm/include/Support</tt> - This directory contains generic
792 support libraries that are independent of LLVM, but are used by LLVM.
793 For example, some C++ STL utilities and a Command Line option processing
794 library store their header files here.</li>
795
796 <li><tt>llvm/include/Config</tt> - This directory contains header files
797 configured by the <tt>configure</tt> script. They wrap "standard" UNIX
798 and C header files. Source code can include these header files which
799 automatically take care of the conditional #includes that the
800 <tt>configure</tt> script generates.</li>
801</ol>
802
803</div>
804
805<!-- ======================================================================= -->
806<div class="doc_subsection">
807 <a name="lib"><tt>llvm/lib</tt></a>
808</div>
809
810<div class="doc_text">
811
812<p>This directory contains most of the source files of the LLVM system. In LLVM,
813almost all code exists in libraries, making it very easy to share code among the
814different <a href="#tools">tools</a>.</p>
815
816<dl compact>
817 <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
818 source files that implement core classes like Instruction and BasicBlock.
819
820 <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
821 for the LLVM assembly language parser library.
822
823 <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
824 and write LLVM bytecode.
825
826 <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
827 converter.
828
829 <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
830 different program analyses, such as Dominator Information, Call Graphs,
831 Induction Variables, Interval Identification, Natural Loop Identification,
832 etc...
833
834 <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
835 code for the LLVM to LLVM program transformations, such as Aggressive Dead
836 Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
837 Invariant Code Motion, Dead Global Elimination, and many others...
838
839 <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
840 describe various target architectures for code generation. For example,
841 the llvm/lib/Target/Sparc directory holds the Sparc machine
842 description.<br>
843
844 <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
845 of the code generator: Instruction Selector, Instruction Scheduling, and
846 Register Allocation.
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]847
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]848 <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
849 that corresponds to the header files located in
850 <tt>llvm/include/Support/</tt>.
851</dl>
John Criswell7a73b802003-06-30 21:59:07 +0000[diff] [blame]852
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]853</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]854
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]855<!-- ======================================================================= -->
856<div class="doc_subsection">
857 <a name="runtime"><tt>llvm/runtime</tt></a>
858</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]859
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]860<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]861
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]862<p>This directory contains libraries which are compiled into LLVM bytecode and
863used when linking programs with the GCC front end. Most of these libraries are
864skeleton versions of real libraries; for example, libc is a stripped down
865version of glibc.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]866
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]867<p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
868end to compile.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]869
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]870</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]871
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]872<!-- ======================================================================= -->
873<div class="doc_subsection">
874 <a name="test"><tt>llvm/test</tt></a>
875</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]876
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]877<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]878
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]879<p>This directory contains regression tests and source code that is used to test
880the LLVM infrastructure.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]881
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]882</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]883
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]884<!-- ======================================================================= -->
885<div class="doc_subsection">
886 <a name="tools"><tt>llvm/tools</tt></a>
887</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]888
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]889<div class="doc_text">
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]890
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]891<p>The <b>tools</b> directory contains the executables built out of the
892libraries above, which form the main part of the user interface. You can
893always get help for a tool by typing <tt>tool_name --help</tt>. The
894following is a brief introduction to the most important tools.</p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]895
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]896<dl compact>
897 <dt>
John Criswell20d2d3e2003-10-10 14:26:14 +0000[diff] [blame]898
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]899 <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
900 analysis on an input LLVM bytecode file and print out the results. It is
901 primarily useful for debugging analyses, or familiarizing yourself with
902 what an analysis does.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]903
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]904 <dt><tt><b>bugpoint</b></tt><dd> <tt>bugpoint</tt> is used to debug
905 optimization passes or code generation backends by narrowing down the
906 given test case to the minimum number of passes and/or instructions that
907 still cause a problem, whether it is a crash or miscompilation. See <a
908 href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
909 on using <tt>bugpoint</tt>.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]910
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]911 <dt><tt><b>llvm-ar</b></tt><dd>The archiver produces an archive containing
912 the given LLVM bytecode files, optionally with an index for faster
913 lookup.<p>
914
915 <dt><tt><b>llvm-as</b></tt><dd>The assembler transforms the human readable
916 LLVM assembly to LLVM bytecode.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]917
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]918 <dt><tt><b>llvm-dis</b></tt><dd>The disassembler transforms the LLVM
919 bytecode to human readable LLVM assembly. Additionally, it can convert
920 LLVM bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]921
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]922 <dt><tt><b>llvm-link</b></tt><dd> <tt>llvm-link</tt>, not surprisingly,
923 links multiple LLVM modules into a single program.<p>
924
925 <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
926 can directly execute LLVM bytecode (although very slowly...). In addition
927 to a simple interpreter, <tt>lli</tt> also has a tracing mode (entered by
928 specifying <tt>-trace</tt> on the command line). Finally, for
929 architectures that support it (currently only x86 and Sparc), by default,
930 <tt>lli</tt> will function as a Just-In-Time compiler (if the
931 functionality was compiled in), and will execute the code <i>much</i>
932 faster than the interpreter.<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000[diff] [blame]933
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]934 <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
935 which translates LLVM bytecode to a SPARC or x86 assembly file.<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000[diff] [blame]936
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]937 <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC-based C frontend
938 that has been retargeted to emit LLVM code as the machine code output. It
939 works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
940 -o</tt> options that are typically used. The source code for the
941 <tt>llvmgcc</tt> tool is currently not included in the LLVM CVS tree
942 because it is quite large and not very interesting.<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000[diff] [blame]943
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]944 <ol>
945 <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
946 <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler. This
947 tool actually assembles LLVM assembly to LLVM bytecode,
948 performs a variety of optimizations, and outputs LLVM bytecode. Thus
949 when you invoke <tt>llvmgcc -c x.c -o x.o</tt>, you are causing
950 <tt>gccas</tt> to be run, which writes the <tt>x.o</tt> file (which is
951 an LLVM bytecode file that can be disassembled or manipulated just like
952 any other bytecode file). The command line interface to <tt>gccas</tt>
953 is designed to be as close as possible to the <b>system</b>
954 `<tt>as</tt>' utility so that the gcc frontend itself did not have to be
955 modified to interface to a "weird" assembler.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]956
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]957 <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several LLVM
958 bytecode files into one bytecode file and does some optimization. It is
959 the linker invoked by the GCC frontend when multiple .o files need to be
960 linked together. Like <tt>gccas</tt>, the command line interface of
961 <tt>gccld</tt> is designed to match the system linker, to aid
962 interfacing with the GCC frontend.<p>
963 </ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]964
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]965 <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
966 series of LLVM to LLVM transformations (which are specified on the command
967 line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
968 command is a good way to get a list of the program transformations
969 available in LLVM.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]970
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]971</dl>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]972
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]973</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]974
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]975<!-- ======================================================================= -->
976<div class="doc_subsection">
977 <a name="utils"><tt>llvm/utils</tt></a>
978</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]979
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]980<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]981
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]982<p>This directory contains utilities for working with LLVM source code, and some
983of the utilities are actually required as part of the build process because they
984are code generators for parts of LLVM infrastructure.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]985
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]986<dl compact>
987 <td><tt><b>Burg/</b></tt><dd> <tt>Burg</tt> is an instruction selector
988 generator -- it builds trees on which it then performs pattern-matching to
989 select instructions according to the patterns the user has specified. Burg
990 is currently used in the Sparc V9 backend.<p>
John Criswell0b459202003-07-08 20:35:59 +0000[diff] [blame]991
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]992 <dt><tt><b>codegen-diff</b></tt><dd> <tt>codegen-diff</tt> is a script
993 that finds differences between code that LLC generates and code that LLI
994 generates. This is a useful tool if you are debugging one of them,
995 assuming that the other generates correct output. For the full user
996 manual, run <tt>`perldoc codegen-diff'</tt>.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]997
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]998 <dt><tt><b>cvsupdate</b></tt><dd> <tt>cvsupdate</tt> is a script that will
999 update your CVS tree, but produce a much cleaner and more organized output
1000 than simply running <tt>`cvs -z3 up -dP'</tt> will. For example, it will group
1001 together all the new and updated files and modified files in separate
1002 sections, so you can see at a glance what has changed. If you are at the
1003 top of your LLVM CVS tree, running <tt>utils/cvsupdate</tt> is the
1004 preferred way of updating the tree.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1005
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1006 <dt><tt><b>emacs/</b></tt><dd> The <tt>emacs</tt> directory contains
1007 syntax-highlighting files which will work with Emacs and XEmacs editors,
1008 providing syntax highlighting support for LLVM assembly files and TableGen
1009 description files. For information on how to use the syntax files, consult
1010 the <tt>README</tt> file in that directory.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1011
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1012 <dt><tt><b>getsrcs.sh</b></tt><dd> The <tt>getsrcs.sh</tt> script finds
1013 and outputs all non-generated source files, which is useful if one wishes
1014 to do a lot of development across directories and does not want to
1015 individually find each file. One way to use it is to run, for example:
1016 <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
1017 tree.<p>
1018
1019 <dt><tt><b>makellvm</b></tt><dd> The <tt>makellvm</tt> script compiles all
1020 files in the current directory and then compiles and links the tool that
1021 is the first argument. For example, assuming you are in the directory
1022 <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
1023 simply running <tt>makellvm llc</tt> will make a build of the current
1024 directory, switch to directory <tt>llvm/tools/llc</tt> and build it,
1025 causing a re-linking of LLC.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1026
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1027 <dt><tt><b>NightlyTest.pl</b></tt> and
1028 <tt><b>NightlyTestTemplate.html</b></tt><dd> These files are used in a
1029 cron script to generate nightly status reports of the functionality of
1030 tools, and the results can be seen by following the appropriate link on
1031 the <a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a>.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1032
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1033 <dt><tt><b>TableGen/</b></tt><dd> The <tt>TableGen</tt> directory contains
1034 the tool used to generate register descriptions, instruction set
1035 descriptions, and even assemblers from common TableGen description
1036 files.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1037
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1038 <dt><tt><b>vim/</b></tt><dd> The <tt>vim</tt> directory contains
1039 syntax-highlighting files which will work with the VIM editor, providing
1040 syntax highlighting support for LLVM assembly files and TableGen
1041 description files. For information on how to use the syntax files, consult
1042 the <tt>README</tt> file in that directory.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1043
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1044</dl>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1045
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1046</div>
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1047
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1048<!-- *********************************************************************** -->
1049<div class="doc_section">
1050 <a name="tutorial">An Example Using the LLVM Tool Chain</a>
1051</div>
1052<!-- *********************************************************************** -->
Misha Brukmanc103adf2003-08-11 18:45:46 +0000[diff] [blame]1053
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1054<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1055
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1056<ol>
1057 <li>First, create a simple C file, name it 'hello.c':
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1058 <pre>
1059 #include &lt;stdio.h&gt;
1060 int main() {
1061 printf("hello world\n");
1062 return 0;
1063 }
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1064 </pre></li>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1065
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1066 <li><p>Next, compile the C file into a LLVM bytecode file:</p>
1067 <p><tt>% llvmgcc hello.c -o hello</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1068
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1069 <p>This will create two result files: <tt>hello</tt> and
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1070 <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
1071 corresponds the the compiled program and the library facilities that it
1072 required. <tt>hello</tt> is a simple shell script that runs the bytecode
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1073 file with <tt>lli</tt>, making the result directly executable.</p></li>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1074
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1075 <li><p>Run the program. To make sure the program ran, execute one of the
1076 following commands:</p>
John Criswell8df90e02003-06-11 20:46:40 +0000[diff] [blame]1077
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1078 <p><tt>% ./hello</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1079
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1080 <p>or</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1081
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1082 <p><tt>% lli hello.bc</tt></p></li>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1083
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1084 <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
1085 code:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1086
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1087 <p><tt>% llvm-dis &lt; hello.bc | less</tt><p></li>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1088
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1089 <li><p>Compile the program to native Sparc assembly using the code
1090 generator (assuming you are currently on a Sparc system):</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1091
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1092 <p><tt>% llc hello.bc -o hello.s</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1093
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1094 <li><p>Assemble the native sparc assemble file into a program:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1095
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1096 <p><tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1097
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1098 <li><p>Execute the native sparc program:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1099
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1100 <p><tt>% ./hello.sparc</tt></p></li>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1101
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1102</ol>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1103
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1104</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1105
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1106<!-- *********************************************************************** -->
1107<div class="doc_section">
1108 <a name="problems">Common Problems</a>
1109</div>
1110<!-- *********************************************************************** -->
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]1111
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1112<div class="doc_text">
John Criswellce760f62003-07-03 16:01:38 +0000[diff] [blame]1113
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1114<p>If you are having problems building or using LLVM, or if you have any other
1115general questions about LLVM, please consult the <a href="FAQ.html">Frequently
1116Asked Questions</a> page.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1117
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1118</div>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1119
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1120<!-- *********************************************************************** -->
1121<div class="doc_section">
1122 <a name="links">Links</a>
1123</div>
1124<!-- *********************************************************************** -->
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1125
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1126<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1127
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1128<p>This document is just an <b>introduction</b> to how to use LLVM to do
1129some simple things... there are many more interesting and complicated things
1130that you can do that aren't documented here (but we'll gladly accept a patch
1131if you want to write something up!). For more information about LLVM, check
1132out:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000[diff] [blame]1133
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1134<ul>
1135 <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
1136 <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
1137 <li><a href="http://llvm.cs.uiuc.edu/docs/Projects.html">Starting a Project
1138 that Uses LLVM</a></li>
1139</ul>
1140
1141</div>
1142
1143<!-- *********************************************************************** -->
1144
1145<hr>
Misha Brukman142207b2003-11-22 01:30:01 +0000[diff] [blame]1146<address>
1147 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1148 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1149 Last modified: $Date$
Misha Brukman142207b2003-11-22 01:30:01 +0000[diff] [blame]1150</address>
Misha Brukman00c73d22003-11-07 19:43:14 +0000[diff] [blame]1151
1152</body>
Guochun Shif4688a82002-07-17 23:05:56 +0000[diff] [blame]1153</html>