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