blob: 6490c0cf280fc6fb323c91ea429f05d7838af139 [file] [log] [blame]
Misha Brukman00c73d22003-11-07 19:43:14 +00001<!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 +00003<html>
Misha Brukman00c73d22003-11-07 19:43:14 +00004<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 +00009
Misha Brukman00c73d22003-11-07 19:43:14 +000010<div class="doc_title">
11 Getting Started with the LLVM System
12</div>
John Criswell85ed3612003-06-12 19:34:44 +000013
Misha Brukman00c73d22003-11-07 19:43:14 +000014<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 +000018 <ol>
Misha Brukman00c73d22003-11-07 19:43:14 +000019 <li><a href="#hardware">Hardware</a>
20 <li><a href="#software">Software</a>
21 </ol></li>
John Criswell7a73b802003-06-30 21:59:07 +000022
Misha Brukman00c73d22003-11-07 19:43:14 +000023 <li><a href="#starting">Getting Started with LLVM</a>
John Criswell0b459202003-07-08 20:35:59 +000024 <ol>
Misha Brukman00c73d22003-11-07 19:43:14 +000025 <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>
Chris Lattnera553f622004-03-25 20:38:40 +000033 <li><a href="#optionalconfig">Optional Configuration Items</a>
Misha Brukman00c73d22003-11-07 19:43:14 +000034 </ol></li>
John Criswell0b459202003-07-08 20:35:59 +000035
Misha Brukman00c73d22003-11-07 19:43:14 +000036 <li><a href="#layout">Program layout</a>
37 <ol>
38 <li><a href="#cvsdir"><tt>CVS</tt> directories</a>
39 <li><a href="#include"><tt>llvm/include</tt></a>
40 <li><a href="#lib"><tt>llvm/lib</tt></a>
41 <li><a href="#runtime"><tt>llvm/runtime</tt></a>
42 <li><a href="#test"><tt>llvm/test</tt></a>
43 <li><a href="#tools"><tt>llvm/tools</tt></a>
44 <li><a href="#utils"><tt>llvm/utils</tt></a>
45 </ol></li>
John Criswell0f6d7c02003-10-27 18:18:16 +000046
Misha Brukman00c73d22003-11-07 19:43:14 +000047 <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
48 <li><a href="#problems">Common Problems</a>
49 <li><a href="#links">Links</a>
50</ul>
51
52<p>By:
Misha Brukman00c73d22003-11-07 19:43:14 +000053 <a href="mailto:criswell@uiuc.edu">John Criswell</a>,
Chris Lattnera553f622004-03-25 20:38:40 +000054 <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
55 <a href="http://misha.brukman.net">Misha Brukman</a>,
56 <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>, and
57 <a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>.</p>
Misha Brukman00c73d22003-11-07 19:43:14 +000058
59
60<!-- *********************************************************************** -->
61<div class="doc_section">
62 <a name="overview"><b>Overview</b></a>
63</div>
64<!-- *********************************************************************** -->
65
66<div class="doc_text">
67
68<p>Welcome to LLVM! In order to get started, you first need to know some
69basic information.</p>
70
71<p>First, LLVM comes in two pieces. The first piece is the LLVM suite. This
72contains all of the tools, libraries, and header files needed to use the low
73level virtual machine. It contains an assembler, disassembler, bytecode
74analyzer, and bytecode optimizer. It also contains a test suite that can be
75used to test the LLVM tools and the GCC front end.</p>
76
77<p>The second piece is the GCC front end. This component provides a version of
78GCC that compiles C and C++ code into LLVM bytecode. Currently, the GCC front
79end is a modified version of GCC 3.4 (we track the GCC 3.4 development). Once
80compiled into LLVM bytecode, a program can be manipulated with the LLVM tools
81from the LLVM suite.</p>
82
83</div>
84
85<!-- *********************************************************************** -->
86<div class="doc_section">
87 <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
88</div>
89<!-- *********************************************************************** -->
90
91<div class="doc_text">
92
93<p>Here's the short story for getting up and running quickly with LLVM:</p>
94
95<ol>
96 <li>Install the GCC front end:
97 <ol>
98 <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt>
99 <li><tt>gunzip --stdout cfrontend.<i>platform</i>.tar.gz | tar -xvf -</tt>
John Criswell364cec42004-03-12 20:31:37 +0000100 <li><b>Sparc and MacOS X Only:</b><br>
101 <tt>cd cfrontend/<i>platform</i><br>
Misha Brukman00c73d22003-11-07 19:43:14 +0000102 ./fixheaders</tt>
103 </ol></li>
104
105 <li>Get the Source Code
106 <ul>
107 <li>With the distributed files:
108 <ol>
109 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
John Criswell364cec42004-03-12 20:31:37 +0000110 <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
Misha Brukman00c73d22003-11-07 19:43:14 +0000111 <li><tt>cd llvm</tt>
112 </ol></li>
113
114 <li>With anonymous CVS access:
115 <ol>
116 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
117 <li><tt>cvs -d
118 :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt></li>
119 <li>Hit the return key when prompted for the password.
120 <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
121 co llvm</tt></li>
122 <li><tt>cd llvm</tt></li>
123 </ol></li>
124 </ul></li>
125
126 <li>Configure the LLVM Build Environment
127 <ol>
128 <li>Change directory to where you want to store the LLVM object
129 files and run <tt>configure</tt> to configure the Makefiles and
130 header files for the default platform. Useful options include:
131 <ul>
132 <li><tt>--with-llvmgccdir=<i>directory</i></tt>
John Criswelld000e1d2003-12-18 16:43:17 +0000133 <p>Specify the full pathname of where the LLVM GCC frontend is
134 installed.</p></li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000135 <li><tt>--enable-spec2000=<i>directory</i></tt>
136 <p>Enable the SPEC2000 benchmarks for testing. The SPEC2000
137 benchmarks should be available in
138 <tt><i>directory</i></tt>.</p></li>
139 </ul>
140 </ol></li>
141
142 <li>Build the LLVM Suite:
143 <ol>
144 <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
145 <li><tt>gmake -k |& tee gnumake.out
146 &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
147 </ol>
148
149</ol>
150
151<p>Consult the <a href="starting">Getting Started with LLVM</a> section for
152detailed information on configuring and compiling LLVM. See <a
153href="#environment">Setting Up Your Environment</a> for tips that simplify
154working with the GCC front end and LLVM tools. Go to <a href="#layout">Program
155Layout</a> to learn about the layout of the source code tree.</p>
156
157</div>
158
159<!-- *********************************************************************** -->
160<div class="doc_section">
161 <a name="requirements"><b>Requirements</b></a>
162</div>
163<!-- *********************************************************************** -->
164
165<div class="doc_text">
166
167<p>Before you begin to use the LLVM system, review the requirements given below.
168This may save you some trouble by knowing ahead of time what hardware and
169software you will need.</p>
170
171</div>
172
173<!-- ======================================================================= -->
174<div class="doc_subsection">
175 <a name="hardware"><b>Hardware</b></a>
176</div>
177
178<div class="doc_text">
179
180<p>LLVM is known to work on the following platforms:</p>
181
182<ul>
183
184 <li>Linux on x86 (Pentium and above)
185 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000186 <li>Approximately 918 MB of Free Disk Space
Misha Brukman00c73d22003-11-07 19:43:14 +0000187 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000188 <li>Source code: 28 MB</li>
189 <li>Object code: 850 MB</li>
190 <li>GCC front end: 40 MB</li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000191 </ul></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000192 </ul>
193 </li>
194
Misha Brukman00c73d22003-11-07 19:43:14 +0000195 <li>Solaris on SparcV9 (Ultrasparc)
196 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000197 <li>Approximately 1.52 GB of Free Disk Space
Misha Brukman00c73d22003-11-07 19:43:14 +0000198 <ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000199 <li>Source code: 28 MB</li>
200 <li>Object code: 1470 MB</li>
201 <li>GCC front end: 50 MB</li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000202 </ul></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000203 </ul>
204 </li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000205
John Criswelld000e1d2003-12-18 16:43:17 +0000206 <li>FreeBSD on x86 (Pentium and above)
207 <ul>
208 <li>Approximately 918 MB of Free Disk Space
209 <ul>
210 <li>Source code: 28 MB</li>
211 <li>Object code: 850 MB</li>
212 <li>GCC front end: 40 MB</li>
213 </ul></li>
214 </ul>
215 </li>
216
John Criswelld000e1d2003-12-18 16:43:17 +0000217 <li>MacOS X on PowerPC
218 <ul>
219 <li>No native code generation
220 <li>Approximately 1.20 GB of Free Disk Space
221 <ul>
222 <li>Source code: 28 MB</li>
223 <li>Object code: 1160 MB</li>
224 <li>GCC front end: 40 MB</li>
225 </ul></li>
226 </ul>
227
228 </li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000229</ul>
230
231<p>The LLVM suite <i>may</i> compile on other platforms, but it is not
232guaranteed to do so. If compilation is successful, the LLVM utilities should be
233able to assemble, disassemble, analyze, and optimize LLVM bytecode. Code
234generation should work as well, although the generated native code may not work
235on your platform.</p>
236
237<p>The GCC front end is not very portable at the moment. If you want to get it
238to work on another platform, you can download a copy of the source and try to
239compile it on your platform.</p>
240
241</div>
242
243<!-- ======================================================================= -->
244<div class="doc_subsection">
245 <a name="software"><b>Software</b></a>
246</div>
247
248<div class="doc_text">
249
250<p>Compiling LLVM requires that you have several software packages
251installed:</p>
252
253<ul>
254 <li><a href="http://gcc.gnu.org">GCC 3.x with C and C++ language
255 support</a></li>
256
257 <li><a href="http://savannah.gnu.org/projects/make">GNU Make</a></li>
258
259 <li><a href="http://www.gnu.org/software/flex">Flex</a></li>
260
261 <li><a href="http://www.gnu.org/software/bison/bison.html">Bison</a></li>
262</ul>
263
264<p>There are some additional tools that you may want to have when working with
265LLVM:</p>
266
267<ul>
Brian Gaeke5c681b62004-02-08 07:49:04 +0000268 <li><A href="http://www.gnu.org/software/automake">GNU Automake</A></li>
269 <li><A href="http://www.gnu.org/software/autoconf">GNU Autoconf</A></li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000270 <li><A href="http://savannah.gnu.org/projects/m4">GNU M4</A>
271
272 <p>If you want to make changes to the configure scripts, you will need GNU
273 autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 or
Brian Gaeke5c681b62004-02-08 07:49:04 +0000274 higher). You will also need automake. Any old version of
275 automake from 1.4p5 on should work; we only use aclocal from that
276 package.</p></li>
Misha Brukman00c73d22003-11-07 19:43:14 +0000277
278 <li><A href="http://www.codesourcery.com/qm/qmtest">QMTest</A></li>
279 <li><A href="http://www.python.org">Python</A>
280
281 <p>These are needed to use the LLVM test suite.</p></li>
282
283</ul>
284
Misha Brukman00c73d22003-11-07 19:43:14 +0000285<p>The remainder of this guide is meant to get you up and running with
286LLVM and to give you some basic information about the LLVM environment.
287A <a href="#starting">complete guide to installation</a> is provided in the
288next section.</p>
289
290<p>The later sections of this guide describe the <a
291href="#layout">general layout</a> of the the LLVM source tree, a <a
292href="#tutorial">simple example</a> using the LLVM tool chain, and <a
293href="#links">links</a> to find more information about LLVM or to get
294help via e-mail.</p>
295
296</div>
297
298<!-- *********************************************************************** -->
299<div class="doc_section">
300 <a name="starting"><b>Getting Started with LLVM</b></a>
301</div>
302<!-- *********************************************************************** -->
303
304<!-- ======================================================================= -->
305<div class="doc_subsection">
306 <a name="terminology">Terminology and Notation</a>
307</div>
308
309<div class="doc_text">
310
311<p>Throughout this manual, the following names are used to denote paths
312specific to the local system and working environment. <i>These are not
313environment variables you need to set but just strings used in the rest
314of this document below</i>. In any of the examples below, simply replace
315each of these names with the appropriate pathname on your local system.
316All these paths are absolute:</p>
317
Misha Brukman54111c42004-01-20 00:20:17 +0000318<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000319 <dt>SRC_ROOT
320 <dd>
321 This is the top level directory of the LLVM source tree.
John Criswell0f6d7c02003-10-27 18:18:16 +0000322 <p>
323
Misha Brukman00c73d22003-11-07 19:43:14 +0000324 <dt>OBJ_ROOT
325 <dd>
326 This is the top level directory of the LLVM object tree (i.e. the
327 tree where object files and compiled programs will be placed. It
328 can be the same as SRC_ROOT).
329 <p>
330
331 <dt>LLVMGCCDIR
332 <dd>
333 This is the where the LLVM GCC Front End is installed.
334 <p>
335 For the pre-built GCC front end binaries, the LLVMGCCDIR is
336 <tt>cfrontend/<i>platform</i>/llvm-gcc</tt>.
337</dl>
338
339</div>
340
341<!-- ======================================================================= -->
342<div class="doc_subsection">
343 <a name="environment">Setting Up Your Environment</a>
344</div>
345
346<div class="doc_text">
347
348<p>
349In order to compile and use LLVM, you will need to set some environment
350variables. There are also some shell aliases which you may find useful.
351You can set these on the command line, or better yet, set them in your
352<tt>.cshrc</tt> or <tt>.profile</tt>.
353
Misha Brukman54111c42004-01-20 00:20:17 +0000354<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000355 <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt><i>LLVMGCCDIR</i>/bytecode-libs</tt>
356 <dd>
357 This environment variable helps the LLVM GCC front end find bytecode
358 libraries that it will need for compilation.
359 <p>
360
361 <dt>alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/gcc</tt>
362 <dt>alias llvmg++ <i>LLVMGCCDIR</i><tt>/bin/g++</tt>
363 <dd>
364 This alias allows you to use the LLVM C and C++ front ends without putting
365 them in your <tt>PATH</tt> or typing in their complete pathnames.
366</dl>
367
368</div>
369
370<!-- ======================================================================= -->
371<div class="doc_subsection">
Misha Brukman54111c42004-01-20 00:20:17 +0000372 <a name="unpack">Unpacking the LLVM Archives</a>
Misha Brukman00c73d22003-11-07 19:43:14 +0000373</div>
374
375<div class="doc_text">
376
377<p>
378If you have the LLVM distribution, you will need to unpack it before you
John Criswelld000e1d2003-12-18 16:43:17 +0000379can begin to compile it. LLVM is distributed as a set of two files: the LLVM
380suite and the LLVM GCC front end compiled for your platform. Each
Misha Brukman00c73d22003-11-07 19:43:14 +0000381file is a TAR archive that is compressed with the gzip program.
382</p>
383
John Criswelld000e1d2003-12-18 16:43:17 +0000384<p> The files are as follows:
Misha Brukman54111c42004-01-20 00:20:17 +0000385<dl>
John Criswell364cec42004-03-12 20:31:37 +0000386 <dt>llvm-1.2.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000387 <dd>This is the source code to the LLVM suite.
388 <p>
389
John Criswell364cec42004-03-12 20:31:37 +0000390 <dt>cfrontend-1.2.sparc-sun-solaris2.8.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000391 <dd>This is the binary release of the GCC front end for Solaris/Sparc.
392 <p>
393
John Criswell364cec42004-03-12 20:31:37 +0000394 <dt>cfrontend-1.2.i686-redhat-linux-gnu.tar.gz
Misha Brukman00c73d22003-11-07 19:43:14 +0000395 <dd>This is the binary release of the GCC front end for Linux/x86.
John Criswelld000e1d2003-12-18 16:43:17 +0000396 <p>
397
John Criswell364cec42004-03-12 20:31:37 +0000398 <dt>cfrontend-1.2.i386-unknown-freebsd5.1.tar.gz
John Criswelld000e1d2003-12-18 16:43:17 +0000399 <dd>This is the binary release of the GCC front end for FreeBSD/x86.
400 <p>
401
John Criswell364cec42004-03-12 20:31:37 +0000402 <dt>cfrontend-1.2.powerpc-apple-darwin7.0.0.tar.gz
John Criswelld000e1d2003-12-18 16:43:17 +0000403 <dd>This is the binary release of the GCC front end for MacOS X/PPC.
Misha Brukman00c73d22003-11-07 19:43:14 +0000404</dl>
405
406</div>
407
408<!-- ======================================================================= -->
409<div class="doc_subsection">
Misha Brukman54111c42004-01-20 00:20:17 +0000410 <a name="checkout">Checkout LLVM from CVS</a>
Misha Brukman00c73d22003-11-07 19:43:14 +0000411</div>
412
413<div class="doc_text">
414
415<p>If you have access to our CVS repository, you can get a fresh copy of
416the entire source code. All you need to do is check it out from CVS as
417follows:</p>
418
419<ul>
420<li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
421 <li><tt>cvs -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt>
422 <li>Hit the return key when prompted for the password.
423 <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
424 llvm</tt>
425</ul>
426
427<p>This will create an '<tt>llvm</tt>' directory in the current
428directory and fully populate it with the LLVM source code, Makefiles,
429test directories, and local copies of documentation files.</p>
430
Misha Brukman54111c42004-01-20 00:20:17 +0000431<p>If you want to get a specific release (as opposed to the most recent
432revision), you can specify a label. The following releases have the following
433label:</p>
434
John Criswelld000e1d2003-12-18 16:43:17 +0000435<ul>
436 <li>
John Criswell364cec42004-03-12 20:31:37 +0000437 Release 1.2: <b>RELEASE_12</b>
438 </li>
439
440 <li>
John Criswelld000e1d2003-12-18 16:43:17 +0000441 Release 1.1: <b>RELEASE_11</b>
442 </li>
443
444 <li>
445 Release 1.0: <b>RELEASE_1</b>
446 </li>
447</ul>
John Criswelld000e1d2003-12-18 16:43:17 +0000448
John Criswell364cec42004-03-12 20:31:37 +0000449<p>
450If you would like to get the GCC front end source code, you can also get it
451from the CVS repository:
452<ul>
453 <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
454 llvm-gcc</tt>
455</ul>
456</p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000457
458</div>
459
460<!-- ======================================================================= -->
461<div class="doc_subsection">
Misha Brukman54111c42004-01-20 00:20:17 +0000462 <a name="installcf">Install the GCC Front End</a>
Misha Brukman00c73d22003-11-07 19:43:14 +0000463</div>
464
465<div class="doc_text">
466
467<p>Before configuring and compiling the LLVM suite, you need to extract the LLVM
468GCC front end from the binary distribution. It is used for building the
469bytecode libraries later used by the GCC front end for linking programs, and its
470location must be specified when the LLVM suite is configured.</p>
471
472<p>To install the GCC front end, do the following:</p>
473
474<ol>
475 <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
John Criswelld000e1d2003-12-18 16:43:17 +0000476 <li><tt>gunzip --stdout cfrontend-<i>version</i>.<i>platform</i>.tar.gz | tar -xvf
Misha Brukman00c73d22003-11-07 19:43:14 +0000477 -</tt></li>
478</ol>
479
John Criswelld000e1d2003-12-18 16:43:17 +0000480<p>If you are using Solaris/Sparc or MacOS X/PPC, you will need to fix the
481header files:</p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000482
John Criswell364cec42004-03-12 20:31:37 +0000483<p><tt>cd cfrontend/<i>platform</i><br>
Misha Brukman00c73d22003-11-07 19:43:14 +0000484 ./fixheaders</tt></p>
485
486<p>The binary versions of the GCC front end may not suit all of your needs. For
487example, the binary distribution may include an old version of a system header
488file, not "fix" a header file that needs to be fixed for GCC, or it may be
489linked with libraries not available on your system.</p>
490
491<p>In cases like these, you may want to try <a
492href="CFEBuildInstrs.html">building the GCC front end from source.</a> This is
493not for the faint of heart, so be forewarned.</p>
494
495</div>
496
497<!-- ======================================================================= -->
498<div class="doc_subsection">
499 <a name="config">Local LLVM Configuration</a>
500</div>
501
502<div class="doc_text">
503
504<p>Once checked out from the CVS repository, the LLVM suite source code must be
505configured via the <tt>configure</tt> script. This script sets variables in
506<tt>llvm/Makefile.config</tt> and <tt>llvm/include/Config/config.h</tt>. It
John Criswelld000e1d2003-12-18 16:43:17 +0000507also populates <i>OBJ_ROOT</i> with the Makefiles needed to begin building
508LLVM.</p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000509
510<p>The following environment variables are used by the <tt>configure</tt>
511script to configure the build system:</p>
512
513<table border=1>
514 <tr>
515 <th>Variable</th>
516 <th>Purpose</th>
517 </tr>
518
519 <tr>
520 <td>CC</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
527 <tr>
528 <td>CXX</td>
529 <td>Tells <tt>configure</tt> which C++ compiler to use. By default,
530 <tt>configure</tt> will look for the first GCC C++ compiler in
531 <tt>PATH</tt>. Use this variable to override
532 <tt>configure</tt>'s default behavior.</td>
533 </tr>
534</table>
535
536<p>The following options can be used to set or enable LLVM specific options:</p>
537
Misha Brukman54111c42004-01-20 00:20:17 +0000538<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000539 <dt><i>--with-llvmgccdir=LLVMGCCDIR</i>
540 <dd>
John Criswell364cec42004-03-12 20:31:37 +0000541 Path to the location where the LLVM GCC front end binaries and
John Criswelld000e1d2003-12-18 16:43:17 +0000542 associated libraries were installed. This must be specified as an
543 absolute pathname.
Misha Brukman00c73d22003-11-07 19:43:14 +0000544 <p>
545 <dt><i>--enable-optimized</i>
546 <dd>
547 Enables optimized compilation by default (debugging symbols are removed
548 and GCC optimization flags are enabled). The default is to use an
549 unoptimized build (also known as a debug build).
550 <p>
551 <dt><i>--enable-jit</i>
552 <dd>
John Criswelld000e1d2003-12-18 16:43:17 +0000553 Compile the Just In Time (JIT) compiler functionality. This is not
554 available
Misha Brukman00c73d22003-11-07 19:43:14 +0000555 on all platforms. The default is dependent on platform, so it is best
556 to explicitly enable it if you want it.
557 <p>
558 <dt><i>--enable-spec2000</i>
559 <dt><i>--enable-spec2000=&lt;<tt>directory</tt>&gt;</i>
560 <dd>
561 Enable the use of SPEC2000 when testing LLVM. This is disabled by default
562 (unless <tt>configure</tt> finds SPEC2000 installed). By specifying
563 <tt>directory</tt>, you can tell configure where to find the SPEC2000
564 benchmarks. If <tt>directory</tt> is left unspecified, <tt>configure</tt>
565 uses the default value
566 <tt>/home/vadve/shared/benchmarks/speccpu2000/benchspec</tt>.
John Criswell364cec42004-03-12 20:31:37 +0000567 <p>
568 <dt><i>--enable-spec95</i>
569 <dt><i>--enable-spec95=&lt;<tt>directory</tt>&gt;</i>
570 <dd>
571 Enable the use of SPEC95 when testing LLVM. It is similar to the
572 <i>--enable-spec2000</i> option.
573 <p>
574 <dt><i>--enable-povray</i>
575 <dt><i>--enable-povray=&lt;<tt>directory</tt>&gt;</i>
576 <dd>
577 Enable the use of Povray as an external test. Versions of Povray written
578 in C should work. This option is similar to the <i>--enable-spec2000</i>
579 option.
Misha Brukman00c73d22003-11-07 19:43:14 +0000580</dl>
581
582<p>To configure LLVM, follow these steps:</p>
583
584<ol>
585 <li>Change directory into the object root directory:
John Criswell0f6d7c02003-10-27 18:18:16 +0000586 <br>
Misha Brukman00c73d22003-11-07 19:43:14 +0000587 <tt>cd <i>OBJ_ROOT</i></tt>
John Criswell0f6d7c02003-10-27 18:18:16 +0000588 <p>
John Criswell0f6d7c02003-10-27 18:18:16 +0000589
Misha Brukman00c73d22003-11-07 19:43:14 +0000590 <li>Run the <tt>configure</tt> script located in the LLVM source tree:
591 <br>
592 <tt><i>SRC_ROOT</i>/configure</tt>
John Criswell0f6d7c02003-10-27 18:18:16 +0000593 <p>
Misha Brukman00c73d22003-11-07 19:43:14 +0000594</ol>
John Criswell85ed3612003-06-12 19:34:44 +0000595
Misha Brukman00c73d22003-11-07 19:43:14 +0000596<p>In addition to running <tt>configure</tt>, you must set the
597<tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
598This environment variable is used to locate "system" libraries like
599"<tt>-lc</tt>" and "<tt>-lm</tt>" when linking. This variable should be set to
John Criswelld000e1d2003-12-18 16:43:17 +0000600the absolute path of the <tt>bytecode-libs</tt> subdirectory of the GCC front
601end, or <i>LLVMGCCDIR</i>/<tt>bytecode-libs</tt>. For example, one might set
Misha Brukman00c73d22003-11-07 19:43:14 +0000602<tt>LLVM_LIB_SEARCH_PATH</tt> to
John Criswelld000e1d2003-12-18 16:43:17 +0000603<tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the x86
Misha Brukman00c73d22003-11-07 19:43:14 +0000604version of the GCC front end on our research machines.</p>
John Criswell7a73b802003-06-30 21:59:07 +0000605
Misha Brukman00c73d22003-11-07 19:43:14 +0000606</div>
John Criswell85ed3612003-06-12 19:34:44 +0000607
Misha Brukman00c73d22003-11-07 19:43:14 +0000608<!-- ======================================================================= -->
609<div class="doc_subsection">
610 <a name="compile">Compiling the LLVM Suite Source Code</a>
611</div>
John Criswell85ed3612003-06-12 19:34:44 +0000612
Misha Brukman00c73d22003-11-07 19:43:14 +0000613<div class="doc_text">
John Criswell0b459202003-07-08 20:35:59 +0000614
Misha Brukman00c73d22003-11-07 19:43:14 +0000615<p>Once you have configured LLVM, you can build it. There are three types of
616builds:</p>
John Criswell0b459202003-07-08 20:35:59 +0000617
Misha Brukman54111c42004-01-20 00:20:17 +0000618<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000619 <dt>Debug Builds
John Criswellce760f62003-07-03 16:01:38 +0000620 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000621 These builds are the default when one types <tt>gmake</tt> (unless the
622 <tt>--enable-optimized</tt> option was used during configuration). The
623 build system will compile the tools and libraries with debugging
624 information.
625 <p>
626
627 <dt>Release (Optimized) Builds
John Criswellce760f62003-07-03 16:01:38 +0000628 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000629 These builds are enabled with the <tt>--enable-optimized</tt> option to
630 <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
631 <tt>gmake</tt> command line. For these builds, the build system will
632 compile the tools and libraries with GCC optimizations enabled and strip
633 debugging information from the libraries and executables it generates.
634 <p>
635
636 <dt>Profile Builds
John Criswellce760f62003-07-03 16:01:38 +0000637 <dd>
Misha Brukman00c73d22003-11-07 19:43:14 +0000638 These builds are for use with profiling. They compile profiling
639 information into the code for use with programs like <tt>gprof</tt>.
640 Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
641 on the <tt>gmake</tt> command line.
642</dl>
John Criswell7a73b802003-06-30 21:59:07 +0000643
Misha Brukman00c73d22003-11-07 19:43:14 +0000644<p>Once you have LLVM configured, you can build it by entering the
645<i>OBJ_ROOT</i> directory and issuing the following command:</p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000646
Misha Brukman00c73d22003-11-07 19:43:14 +0000647<p><tt>gmake</tt></p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000648
Misha Brukman00c73d22003-11-07 19:43:14 +0000649<p>If you have multiple processors in your machine, you may wish to use some of
650the parallel build options provided by GNU Make. For example, you could use the
651command:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000652
Misha Brukman00c73d22003-11-07 19:43:14 +0000653<p><tt>gmake -j2</tt></p>
John Criswellce760f62003-07-03 16:01:38 +0000654
Misha Brukman00c73d22003-11-07 19:43:14 +0000655<p>There are several special targets which are useful when working with the LLVM
656source code:</p>
John Criswellce760f62003-07-03 16:01:38 +0000657
Misha Brukman54111c42004-01-20 00:20:17 +0000658<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000659 <dt><tt>gmake clean</tt>
660 <dd>
661 Removes all files generated by the build. This includes object files,
662 generated C/C++ files, libraries, and executables.
663 <p>
John Criswellce760f62003-07-03 16:01:38 +0000664
Misha Brukman00c73d22003-11-07 19:43:14 +0000665 <dt><tt>gmake distclean</tt>
666 <dd>
667 Removes everything that <tt>gmake clean</tt> does, but also removes
668 files generated by <tt>configure</tt>. It attempts to return the
669 source tree to the original state in which it was shipped.
670 <p>
John Criswellce760f62003-07-03 16:01:38 +0000671
Misha Brukman00c73d22003-11-07 19:43:14 +0000672 <dt><tt>gmake install</tt>
673 <dd>
674 Installs LLVM files into the proper location. For the most part,
675 this does nothing, but it does install bytecode libraries into the
676 GCC front end's bytecode library directory. If you need to update
677 your bytecode libraries, this is the target to use once you've built
678 them.
679 <p>
680</dl>
John Criswellce760f62003-07-03 16:01:38 +0000681
Misha Brukman00c73d22003-11-07 19:43:14 +0000682<p>It is also possible to override default values from <tt>configure</tt> by
683declaring variables on the command line. The following are some examples:</p>
John Criswellce760f62003-07-03 16:01:38 +0000684
Misha Brukman54111c42004-01-20 00:20:17 +0000685<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000686 <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
687 <dd>
688 Perform a Release (Optimized) build.
689 <p>
John Criswellce760f62003-07-03 16:01:38 +0000690
Misha Brukman00c73d22003-11-07 19:43:14 +0000691 <dt><tt>gmake ENABLE_PROFILING=1</tt>
692 <dd>
693 Perform a Profiling build.
694 <p>
John Criswellce760f62003-07-03 16:01:38 +0000695
Misha Brukman00c73d22003-11-07 19:43:14 +0000696 <dt><tt>gmake VERBOSE=1</tt>
697 <dd>
698 Print what <tt>gmake</tt> is doing on standard output.
699 <p>
700</dl>
John Criswellce760f62003-07-03 16:01:38 +0000701
Misha Brukman00c73d22003-11-07 19:43:14 +0000702<p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
703it and any subdirectories that it contains. Entering any directory inside the
704LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
705that directory that is out of date.</p>
John Criswellce760f62003-07-03 16:01:38 +0000706
Misha Brukman00c73d22003-11-07 19:43:14 +0000707</div>
John Criswell20d2d3e2003-10-10 14:26:14 +0000708
Misha Brukman00c73d22003-11-07 19:43:14 +0000709<!-- ======================================================================= -->
710<div class="doc_subsection">
711 <a name="objfiles">The Location of LLVM Object Files</a>
712</div>
John Criswell20d2d3e2003-10-10 14:26:14 +0000713
Misha Brukman00c73d22003-11-07 19:43:14 +0000714<div class="doc_text">
John Criswellce760f62003-07-03 16:01:38 +0000715
Misha Brukman00c73d22003-11-07 19:43:14 +0000716<p>The LLVM build system is capable of sharing a single LLVM source tree among
717several LLVM builds. Hence, it is possible to build LLVM for several different
718platforms or configurations using the same source tree.</p>
John Criswellce760f62003-07-03 16:01:38 +0000719
Misha Brukman00c73d22003-11-07 19:43:14 +0000720<p>This is accomplished in the typical autoconf manner:</p>
John Criswellce760f62003-07-03 16:01:38 +0000721
Misha Brukman00c73d22003-11-07 19:43:14 +0000722<ul>
723 <li><p>Change directory to where the LLVM object files should live:</p>
John Criswellce760f62003-07-03 16:01:38 +0000724
Misha Brukman00c73d22003-11-07 19:43:14 +0000725 <p><tt>cd <i>OBJ_ROOT</i></tt></p></li>
John Criswellce760f62003-07-03 16:01:38 +0000726
Misha Brukman00c73d22003-11-07 19:43:14 +0000727 <li><p>Run the <tt>configure</tt> script found in the LLVM source
728 directory:</p>
John Criswellce760f62003-07-03 16:01:38 +0000729
Misha Brukman00c73d22003-11-07 19:43:14 +0000730 <p><tt><i>SRC_ROOT</i>/configure</tt></p></li>
731</ul>
John Criswell85ed3612003-06-12 19:34:44 +0000732
Misha Brukman00c73d22003-11-07 19:43:14 +0000733<p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
734named after the build type:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000735
Misha Brukman54111c42004-01-20 00:20:17 +0000736<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000737 <dt>Debug Builds
738 <dd>
Misha Brukman54111c42004-01-20 00:20:17 +0000739 <dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000740 <dt>Tools
741 <dd><tt><i>OBJ_ROOT</i>/tools/Debug</tt>
742 <dt>Libraries
743 <dd><tt><i>OBJ_ROOT</i>/lib/Debug</tt>
744 </dl>
745 <p>
John Criswell85ed3612003-06-12 19:34:44 +0000746
Misha Brukman00c73d22003-11-07 19:43:14 +0000747 <dt>Release Builds
748 <dd>
Misha Brukman54111c42004-01-20 00:20:17 +0000749 <dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000750 <dt>Tools
751 <dd><tt><i>OBJ_ROOT</i>/tools/Release</tt>
752 <dt>Libraries
753 <dd><tt><i>OBJ_ROOT</i>/lib/Release</tt>
754 </dl>
755 <p>
John Criswell85ed3612003-06-12 19:34:44 +0000756
Misha Brukman00c73d22003-11-07 19:43:14 +0000757 <dt>Profile Builds
758 <dd>
Misha Brukman54111c42004-01-20 00:20:17 +0000759 <dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000760 <dt>Tools
761 <dd><tt><i>OBJ_ROOT</i>/tools/Profile</tt>
762 <dt>Libraries
763 <dd><tt><i>OBJ_ROOT</i>/lib/Profile</tt>
764 </dl>
765</dl>
John Criswell85ed3612003-06-12 19:34:44 +0000766
Misha Brukman00c73d22003-11-07 19:43:14 +0000767</div>
Chris Lattner7fe7f812002-07-24 19:51:14 +0000768
Chris Lattnera553f622004-03-25 20:38:40 +0000769<!-- ======================================================================= -->
770<div class="doc_subsection">
771 <a name="optionalconfig">Optional Configuration Items</a>
772</div>
773
774<div class="doc_text">
775
776<p>
777If you're running on a linux system that supports the "<a
778href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>"
779module, and you have root access on the system, you can set your system up to
780execute LLVM bytecode files directly. To do this, use commands like this (the
781first command may not be required if you are already using the module):</p>
782
783<pre>
784 $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
785 $ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
786 $ chmod u+x hello.bc (if needed)
787 $ ./hello.bc
788</pre>
789
790<p>
791This allows you to execute LLVM bytecode files directly. Thanks to Jack
792Cummings for pointing this out!
793</p>
794
795</div>
796
797
Misha Brukman00c73d22003-11-07 19:43:14 +0000798<!-- *********************************************************************** -->
799<div class="doc_section">
800 <a name="layout"><b>Program Layout</b></a>
801</div>
802<!-- *********************************************************************** -->
John Criswell85ed3612003-06-12 19:34:44 +0000803
Misha Brukman00c73d22003-11-07 19:43:14 +0000804<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000805
Misha Brukman00c73d22003-11-07 19:43:14 +0000806<p>One useful source of information about the LLVM source base is the LLVM <a
John Criswell364cec42004-03-12 20:31:37 +0000807href="http://www.doxygen.org">doxygen</a> documentation available at <tt><a
Misha Brukman00c73d22003-11-07 19:43:14 +0000808href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>.
809The following is a brief introduction to code layout:</p>
John Criswell85ed3612003-06-12 19:34:44 +0000810
Misha Brukman00c73d22003-11-07 19:43:14 +0000811</div>
John Criswell85ed3612003-06-12 19:34:44 +0000812
Misha Brukman00c73d22003-11-07 19:43:14 +0000813<!-- ======================================================================= -->
814<div class="doc_subsection">
815 <a name="cvsdir"><tt>CVS</tt> directories</a>
816</div>
John Criswell85ed3612003-06-12 19:34:44 +0000817
Misha Brukman00c73d22003-11-07 19:43:14 +0000818<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000819
Misha Brukman00c73d22003-11-07 19:43:14 +0000820<p>Every directory checked out of CVS will contain a <tt>CVS</tt> directory; for
821the most part these can just be ignored.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000822
Misha Brukman00c73d22003-11-07 19:43:14 +0000823</div>
John Criswell85ed3612003-06-12 19:34:44 +0000824
Misha Brukman00c73d22003-11-07 19:43:14 +0000825<!-- ======================================================================= -->
826<div class="doc_subsection">
827 <a name="include"><tt>llvm/include</tt></a>
828</div>
829
830<div class="doc_text">
831
832<p>This directory contains public header files exported from the LLVM
833library. The three main subdirectories of this directory are:</p>
834
835<ol>
836 <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
837 specific header files. This directory also has subdirectories for
838 different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
839 <tt>Target</tt>, <tt>Transforms</tt>, etc...</li>
840
841 <li><tt>llvm/include/Support</tt> - This directory contains generic
842 support libraries that are independent of LLVM, but are used by LLVM.
843 For example, some C++ STL utilities and a Command Line option processing
844 library store their header files here.</li>
845
846 <li><tt>llvm/include/Config</tt> - This directory contains header files
847 configured by the <tt>configure</tt> script. They wrap "standard" UNIX
848 and C header files. Source code can include these header files which
849 automatically take care of the conditional #includes that the
850 <tt>configure</tt> script generates.</li>
851</ol>
852
853</div>
854
855<!-- ======================================================================= -->
856<div class="doc_subsection">
857 <a name="lib"><tt>llvm/lib</tt></a>
858</div>
859
860<div class="doc_text">
861
862<p>This directory contains most of the source files of the LLVM system. In LLVM,
863almost all code exists in libraries, making it very easy to share code among the
864different <a href="#tools">tools</a>.</p>
865
Misha Brukman54111c42004-01-20 00:20:17 +0000866<dl>
Misha Brukman00c73d22003-11-07 19:43:14 +0000867 <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
868 source files that implement core classes like Instruction and BasicBlock.
869
870 <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
871 for the LLVM assembly language parser library.
872
873 <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
874 and write LLVM bytecode.
875
876 <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
877 converter.
878
879 <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
880 different program analyses, such as Dominator Information, Call Graphs,
881 Induction Variables, Interval Identification, Natural Loop Identification,
882 etc...
883
884 <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
885 code for the LLVM to LLVM program transformations, such as Aggressive Dead
886 Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
887 Invariant Code Motion, Dead Global Elimination, and many others...
888
889 <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
890 describe various target architectures for code generation. For example,
891 the llvm/lib/Target/Sparc directory holds the Sparc machine
892 description.<br>
893
894 <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
895 of the code generator: Instruction Selector, Instruction Scheduling, and
896 Register Allocation.
John Criswell85ed3612003-06-12 19:34:44 +0000897
Misha Brukman00c73d22003-11-07 19:43:14 +0000898 <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
899 that corresponds to the header files located in
900 <tt>llvm/include/Support/</tt>.
901</dl>
John Criswell7a73b802003-06-30 21:59:07 +0000902
Misha Brukman00c73d22003-11-07 19:43:14 +0000903</div>
John Criswell85ed3612003-06-12 19:34:44 +0000904
Misha Brukman00c73d22003-11-07 19:43:14 +0000905<!-- ======================================================================= -->
906<div class="doc_subsection">
907 <a name="runtime"><tt>llvm/runtime</tt></a>
908</div>
John Criswell85ed3612003-06-12 19:34:44 +0000909
Misha Brukman00c73d22003-11-07 19:43:14 +0000910<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000911
Misha Brukman00c73d22003-11-07 19:43:14 +0000912<p>This directory contains libraries which are compiled into LLVM bytecode and
913used when linking programs with the GCC front end. Most of these libraries are
914skeleton versions of real libraries; for example, libc is a stripped down
915version of glibc.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000916
Misha Brukman00c73d22003-11-07 19:43:14 +0000917<p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
918end to compile.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000919
Misha Brukman00c73d22003-11-07 19:43:14 +0000920</div>
John Criswell85ed3612003-06-12 19:34:44 +0000921
Misha Brukman00c73d22003-11-07 19:43:14 +0000922<!-- ======================================================================= -->
923<div class="doc_subsection">
924 <a name="test"><tt>llvm/test</tt></a>
925</div>
John Criswell85ed3612003-06-12 19:34:44 +0000926
Misha Brukman00c73d22003-11-07 19:43:14 +0000927<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +0000928
Misha Brukman00c73d22003-11-07 19:43:14 +0000929<p>This directory contains regression tests and source code that is used to test
930the LLVM infrastructure.</p>
John Criswell85ed3612003-06-12 19:34:44 +0000931
Misha Brukman00c73d22003-11-07 19:43:14 +0000932</div>
John Criswell85ed3612003-06-12 19:34:44 +0000933
Misha Brukman00c73d22003-11-07 19:43:14 +0000934<!-- ======================================================================= -->
935<div class="doc_subsection">
936 <a name="tools"><tt>llvm/tools</tt></a>
937</div>
John Criswell85ed3612003-06-12 19:34:44 +0000938
Misha Brukman00c73d22003-11-07 19:43:14 +0000939<div class="doc_text">
John Criswell20d2d3e2003-10-10 14:26:14 +0000940
Misha Brukman00c73d22003-11-07 19:43:14 +0000941<p>The <b>tools</b> directory contains the executables built out of the
942libraries above, which form the main part of the user interface. You can
943always get help for a tool by typing <tt>tool_name --help</tt>. The
John Criswell364cec42004-03-12 20:31:37 +0000944following is a brief introduction to the most important tools:</p>
John Criswell20d2d3e2003-10-10 14:26:14 +0000945
Misha Brukman54111c42004-01-20 00:20:17 +0000946<dl>
947 <dt><tt><b>analyze</b></tt> <dd><tt>analyze</tt> is used to run a specific
Misha Brukman00c73d22003-11-07 19:43:14 +0000948 analysis on an input LLVM bytecode file and print out the results. It is
949 primarily useful for debugging analyses, or familiarizing yourself with
950 what an analysis does.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000951
Misha Brukman54111c42004-01-20 00:20:17 +0000952 <dt><tt><b>bugpoint</b></tt> <dd><tt>bugpoint</tt> is used to debug
Misha Brukman00c73d22003-11-07 19:43:14 +0000953 optimization passes or code generation backends by narrowing down the
954 given test case to the minimum number of passes and/or instructions that
955 still cause a problem, whether it is a crash or miscompilation. See <a
956 href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
957 on using <tt>bugpoint</tt>.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000958
Misha Brukman54111c42004-01-20 00:20:17 +0000959 <dt><tt><b>llvm-ar</b></tt> <dd>The archiver produces an archive containing
Misha Brukman00c73d22003-11-07 19:43:14 +0000960 the given LLVM bytecode files, optionally with an index for faster
961 lookup.<p>
962
Misha Brukman54111c42004-01-20 00:20:17 +0000963 <dt><tt><b>llvm-as</b></tt> <dd>The assembler transforms the human readable
Misha Brukman00c73d22003-11-07 19:43:14 +0000964 LLVM assembly to LLVM bytecode.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000965
Misha Brukman00c73d22003-11-07 19:43:14 +0000966 <dt><tt><b>llvm-dis</b></tt><dd>The disassembler transforms the LLVM
Chris Lattner036e6392004-02-14 01:07:17 +0000967 bytecode to human readable LLVM assembly.<p>
John Criswell85ed3612003-06-12 19:34:44 +0000968
Misha Brukman00c73d22003-11-07 19:43:14 +0000969 <dt><tt><b>llvm-link</b></tt><dd> <tt>llvm-link</tt>, not surprisingly,
970 links multiple LLVM modules into a single program.<p>
971
972 <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
973 can directly execute LLVM bytecode (although very slowly...). In addition
974 to a simple interpreter, <tt>lli</tt> also has a tracing mode (entered by
975 specifying <tt>-trace</tt> on the command line). Finally, for
976 architectures that support it (currently only x86 and Sparc), by default,
977 <tt>lli</tt> will function as a Just-In-Time compiler (if the
978 functionality was compiled in), and will execute the code <i>much</i>
979 faster than the interpreter.<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000980
Chris Lattner036e6392004-02-14 01:07:17 +0000981 <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler, which
982 translates LLVM bytecode to a SPARC or x86 assembly file, or to C code (with
983 the -march=c option).<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000984
Misha Brukman00c73d22003-11-07 19:43:14 +0000985 <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC-based C frontend
986 that has been retargeted to emit LLVM code as the machine code output. It
987 works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
988 -o</tt> options that are typically used. The source code for the
989 <tt>llvmgcc</tt> tool is currently not included in the LLVM CVS tree
990 because it is quite large and not very interesting.<p>
Misha Brukmanef0ad412003-10-06 19:23:34 +0000991
Misha Brukman54111c42004-01-20 00:20:17 +0000992 <blockquote>
993 <dl>
994 <dt><tt><b>gccas</b></tt> <dd>This tool is invoked by the
Misha Brukman00c73d22003-11-07 19:43:14 +0000995 <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler. This
996 tool actually assembles LLVM assembly to LLVM bytecode,
997 performs a variety of optimizations, and outputs LLVM bytecode. Thus
998 when you invoke <tt>llvmgcc -c x.c -o x.o</tt>, you are causing
999 <tt>gccas</tt> to be run, which writes the <tt>x.o</tt> file (which is
1000 an LLVM bytecode file that can be disassembled or manipulated just like
1001 any other bytecode file). The command line interface to <tt>gccas</tt>
1002 is designed to be as close as possible to the <b>system</b>
1003 `<tt>as</tt>' utility so that the gcc frontend itself did not have to be
1004 modified to interface to a "weird" assembler.<p>
John Criswell85ed3612003-06-12 19:34:44 +00001005
Misha Brukman54111c42004-01-20 00:20:17 +00001006 <dt><tt><b>gccld</b></tt> <dd><tt>gccld</tt> links together several LLVM
Misha Brukman00c73d22003-11-07 19:43:14 +00001007 bytecode files into one bytecode file and does some optimization. It is
1008 the linker invoked by the GCC frontend when multiple .o files need to be
1009 linked together. Like <tt>gccas</tt>, the command line interface of
1010 <tt>gccld</tt> is designed to match the system linker, to aid
Misha Brukman54111c42004-01-20 00:20:17 +00001011 interfacing with the GCC frontend.</dl><p>
1012 </blockquote>
John Criswell85ed3612003-06-12 19:34:44 +00001013
Misha Brukman00c73d22003-11-07 19:43:14 +00001014 <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
1015 series of LLVM to LLVM transformations (which are specified on the command
1016 line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
1017 command is a good way to get a list of the program transformations
Misha Brukman54111c42004-01-20 00:20:17 +00001018 available in LLVM.
John Criswell85ed3612003-06-12 19:34:44 +00001019
Misha Brukman00c73d22003-11-07 19:43:14 +00001020</dl>
John Criswell85ed3612003-06-12 19:34:44 +00001021
Misha Brukman00c73d22003-11-07 19:43:14 +00001022</div>
John Criswell85ed3612003-06-12 19:34:44 +00001023
Misha Brukman00c73d22003-11-07 19:43:14 +00001024<!-- ======================================================================= -->
1025<div class="doc_subsection">
1026 <a name="utils"><tt>llvm/utils</tt></a>
1027</div>
John Criswell85ed3612003-06-12 19:34:44 +00001028
Misha Brukman00c73d22003-11-07 19:43:14 +00001029<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +00001030
Misha Brukman00c73d22003-11-07 19:43:14 +00001031<p>This directory contains utilities for working with LLVM source code, and some
1032of the utilities are actually required as part of the build process because they
1033are code generators for parts of LLVM infrastructure.</p>
John Criswell85ed3612003-06-12 19:34:44 +00001034
Misha Brukman54111c42004-01-20 00:20:17 +00001035<dl>
1036 <dt><tt><b>Burg/</b></tt> <dd><tt>Burg</tt> is an instruction selector
Misha Brukman00c73d22003-11-07 19:43:14 +00001037 generator -- it builds trees on which it then performs pattern-matching to
1038 select instructions according to the patterns the user has specified. Burg
1039 is currently used in the Sparc V9 backend.<p>
John Criswell0b459202003-07-08 20:35:59 +00001040
Misha Brukman54111c42004-01-20 00:20:17 +00001041 <dt><tt><b>codegen-diff</b></tt> <dd><tt>codegen-diff</tt> is a script
Misha Brukman00c73d22003-11-07 19:43:14 +00001042 that finds differences between code that LLC generates and code that LLI
1043 generates. This is a useful tool if you are debugging one of them,
1044 assuming that the other generates correct output. For the full user
1045 manual, run <tt>`perldoc codegen-diff'</tt>.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001046
Misha Brukman54111c42004-01-20 00:20:17 +00001047 <dt><tt><b>cvsupdate</b></tt> <dd><tt>cvsupdate</tt> is a script that will
Misha Brukman00c73d22003-11-07 19:43:14 +00001048 update your CVS tree, but produce a much cleaner and more organized output
1049 than simply running <tt>`cvs -z3 up -dP'</tt> will. For example, it will group
1050 together all the new and updated files and modified files in separate
1051 sections, so you can see at a glance what has changed. If you are at the
1052 top of your LLVM CVS tree, running <tt>utils/cvsupdate</tt> is the
1053 preferred way of updating the tree.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001054
Misha Brukman54111c42004-01-20 00:20:17 +00001055 <dt><tt><b>emacs/</b></tt> <dd>The <tt>emacs</tt> directory contains
Misha Brukman00c73d22003-11-07 19:43:14 +00001056 syntax-highlighting files which will work with Emacs and XEmacs editors,
1057 providing syntax highlighting support for LLVM assembly files and TableGen
1058 description files. For information on how to use the syntax files, consult
1059 the <tt>README</tt> file in that directory.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001060
Misha Brukman54111c42004-01-20 00:20:17 +00001061 <dt><tt><b>getsrcs.sh</b></tt> <dd>The <tt>getsrcs.sh</tt> script finds
Misha Brukman00c73d22003-11-07 19:43:14 +00001062 and outputs all non-generated source files, which is useful if one wishes
1063 to do a lot of development across directories and does not want to
1064 individually find each file. One way to use it is to run, for example:
1065 <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
1066 tree.<p>
1067
Misha Brukman54111c42004-01-20 00:20:17 +00001068 <dt><tt><b>makellvm</b></tt> <dd>The <tt>makellvm</tt> script compiles all
Misha Brukman00c73d22003-11-07 19:43:14 +00001069 files in the current directory and then compiles and links the tool that
1070 is the first argument. For example, assuming you are in the directory
1071 <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
1072 simply running <tt>makellvm llc</tt> will make a build of the current
1073 directory, switch to directory <tt>llvm/tools/llc</tt> and build it,
1074 causing a re-linking of LLC.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001075
Misha Brukman00c73d22003-11-07 19:43:14 +00001076 <dt><tt><b>NightlyTest.pl</b></tt> and
Misha Brukman54111c42004-01-20 00:20:17 +00001077 <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a
Misha Brukman00c73d22003-11-07 19:43:14 +00001078 cron script to generate nightly status reports of the functionality of
1079 tools, and the results can be seen by following the appropriate link on
1080 the <a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a>.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001081
Misha Brukman54111c42004-01-20 00:20:17 +00001082 <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains
Misha Brukman00c73d22003-11-07 19:43:14 +00001083 the tool used to generate register descriptions, instruction set
1084 descriptions, and even assemblers from common TableGen description
1085 files.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001086
Misha Brukman54111c42004-01-20 00:20:17 +00001087 <dt><tt><b>vim/</b></tt> <dd>The <tt>vim</tt> directory contains
Misha Brukman00c73d22003-11-07 19:43:14 +00001088 syntax-highlighting files which will work with the VIM editor, providing
1089 syntax highlighting support for LLVM assembly files and TableGen
1090 description files. For information on how to use the syntax files, consult
1091 the <tt>README</tt> file in that directory.<p>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001092
Misha Brukman00c73d22003-11-07 19:43:14 +00001093</dl>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001094
Misha Brukman00c73d22003-11-07 19:43:14 +00001095</div>
Misha Brukmanc103adf2003-08-11 18:45:46 +00001096
Misha Brukman00c73d22003-11-07 19:43:14 +00001097<!-- *********************************************************************** -->
1098<div class="doc_section">
1099 <a name="tutorial">An Example Using the LLVM Tool Chain</a>
1100</div>
1101<!-- *********************************************************************** -->
Misha Brukmanc103adf2003-08-11 18:45:46 +00001102
Misha Brukman00c73d22003-11-07 19:43:14 +00001103<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +00001104
Misha Brukman00c73d22003-11-07 19:43:14 +00001105<ol>
1106 <li>First, create a simple C file, name it 'hello.c':
John Criswell85ed3612003-06-12 19:34:44 +00001107 <pre>
1108 #include &lt;stdio.h&gt;
1109 int main() {
1110 printf("hello world\n");
1111 return 0;
1112 }
Misha Brukman00c73d22003-11-07 19:43:14 +00001113 </pre></li>
John Criswell85ed3612003-06-12 19:34:44 +00001114
Misha Brukman00c73d22003-11-07 19:43:14 +00001115 <li><p>Next, compile the C file into a LLVM bytecode file:</p>
1116 <p><tt>% llvmgcc hello.c -o hello</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +00001117
Misha Brukman00c73d22003-11-07 19:43:14 +00001118 <p>This will create two result files: <tt>hello</tt> and
John Criswell85ed3612003-06-12 19:34:44 +00001119 <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
1120 corresponds the the compiled program and the library facilities that it
1121 required. <tt>hello</tt> is a simple shell script that runs the bytecode
Misha Brukman00c73d22003-11-07 19:43:14 +00001122 file with <tt>lli</tt>, making the result directly executable.</p></li>
John Criswell85ed3612003-06-12 19:34:44 +00001123
Misha Brukman00c73d22003-11-07 19:43:14 +00001124 <li><p>Run the program. To make sure the program ran, execute one of the
1125 following commands:</p>
John Criswell8df90e02003-06-11 20:46:40 +00001126
Misha Brukman00c73d22003-11-07 19:43:14 +00001127 <p><tt>% ./hello</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +00001128
Misha Brukman00c73d22003-11-07 19:43:14 +00001129 <p>or</p>
John Criswell85ed3612003-06-12 19:34:44 +00001130
Misha Brukman00c73d22003-11-07 19:43:14 +00001131 <p><tt>% lli hello.bc</tt></p></li>
John Criswell85ed3612003-06-12 19:34:44 +00001132
Misha Brukman00c73d22003-11-07 19:43:14 +00001133 <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
1134 code:</p>
John Criswell85ed3612003-06-12 19:34:44 +00001135
Misha Brukman00c73d22003-11-07 19:43:14 +00001136 <p><tt>% llvm-dis &lt; hello.bc | less</tt><p></li>
John Criswell85ed3612003-06-12 19:34:44 +00001137
Misha Brukman00c73d22003-11-07 19:43:14 +00001138 <li><p>Compile the program to native Sparc assembly using the code
1139 generator (assuming you are currently on a Sparc system):</p>
John Criswell85ed3612003-06-12 19:34:44 +00001140
Misha Brukman00c73d22003-11-07 19:43:14 +00001141 <p><tt>% llc hello.bc -o hello.s</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +00001142
Misha Brukman00c73d22003-11-07 19:43:14 +00001143 <li><p>Assemble the native sparc assemble file into a program:</p>
John Criswell85ed3612003-06-12 19:34:44 +00001144
Misha Brukman00c73d22003-11-07 19:43:14 +00001145 <p><tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt></p>
John Criswell85ed3612003-06-12 19:34:44 +00001146
Misha Brukman00c73d22003-11-07 19:43:14 +00001147 <li><p>Execute the native sparc program:</p>
John Criswell85ed3612003-06-12 19:34:44 +00001148
Misha Brukman00c73d22003-11-07 19:43:14 +00001149 <p><tt>% ./hello.sparc</tt></p></li>
John Criswell85ed3612003-06-12 19:34:44 +00001150
Misha Brukman00c73d22003-11-07 19:43:14 +00001151</ol>
John Criswell85ed3612003-06-12 19:34:44 +00001152
Misha Brukman00c73d22003-11-07 19:43:14 +00001153</div>
John Criswell85ed3612003-06-12 19:34:44 +00001154
Misha Brukman00c73d22003-11-07 19:43:14 +00001155<!-- *********************************************************************** -->
1156<div class="doc_section">
1157 <a name="problems">Common Problems</a>
1158</div>
1159<!-- *********************************************************************** -->
John Criswellce760f62003-07-03 16:01:38 +00001160
Misha Brukman00c73d22003-11-07 19:43:14 +00001161<div class="doc_text">
John Criswellce760f62003-07-03 16:01:38 +00001162
Misha Brukman00c73d22003-11-07 19:43:14 +00001163<p>If you are having problems building or using LLVM, or if you have any other
1164general questions about LLVM, please consult the <a href="FAQ.html">Frequently
1165Asked Questions</a> page.</p>
John Criswell85ed3612003-06-12 19:34:44 +00001166
Misha Brukman00c73d22003-11-07 19:43:14 +00001167</div>
John Criswell85ed3612003-06-12 19:34:44 +00001168
Misha Brukman00c73d22003-11-07 19:43:14 +00001169<!-- *********************************************************************** -->
1170<div class="doc_section">
1171 <a name="links">Links</a>
1172</div>
1173<!-- *********************************************************************** -->
John Criswell85ed3612003-06-12 19:34:44 +00001174
Misha Brukman00c73d22003-11-07 19:43:14 +00001175<div class="doc_text">
John Criswell85ed3612003-06-12 19:34:44 +00001176
Misha Brukman00c73d22003-11-07 19:43:14 +00001177<p>This document is just an <b>introduction</b> to how to use LLVM to do
1178some simple things... there are many more interesting and complicated things
1179that you can do that aren't documented here (but we'll gladly accept a patch
1180if you want to write something up!). For more information about LLVM, check
1181out:</p>
John Criswell85ed3612003-06-12 19:34:44 +00001182
Misha Brukman00c73d22003-11-07 19:43:14 +00001183<ul>
1184 <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
1185 <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
1186 <li><a href="http://llvm.cs.uiuc.edu/docs/Projects.html">Starting a Project
1187 that Uses LLVM</a></li>
1188</ul>
1189
1190</div>
1191
1192<!-- *********************************************************************** -->
1193
1194<hr>
Misha Brukman142207b2003-11-22 01:30:01 +00001195<address>
Misha Brukman54111c42004-01-20 00:20:17 +00001196 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1197 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
1198 <a href="http://validator.w3.org/check/referer"><img
1199 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
1200
Misha Brukman142207b2003-11-22 01:30:01 +00001201 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1202 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
Misha Brukman00c73d22003-11-07 19:43:14 +00001203 Last modified: $Date$
Misha Brukman142207b2003-11-22 01:30:01 +00001204</address>
Misha Brukman00c73d22003-11-07 19:43:14 +00001205
1206</body>
Guochun Shif4688a82002-07-17 23:05:56 +00001207</html>