<li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
<li><a href="#requirements">Requirements</a>
<ol>
- <li><a href="#hardware">Hardware</a>
- <li><a href="#software">Software</a>
- <li><a href="#brokengcc">Broken versions of GCC and other tools</a>
+ <li><a href="#hardware">Hardware</a></li>
+ <li><a href="#software">Software</a></li>
+ <li><a href="#brokengcc">Broken versions of GCC and other tools</a></li>
</ol></li>
<li><a href="#starting">Getting Started with LLVM</a>
<ol>
- <li><a href="#terminology">Terminology and Notation</a>
- <li><a href="#environment">Setting Up Your Environment</a>
- <li><a href="#unpack">Unpacking the LLVM Archives</a>
- <li><a href="#checkout">Checkout LLVM from Subversion</a>
- <li><a href="#installcf">Install the GCC Front End</a>
- <li><a href="#config">Local LLVM Configuration</a>
- <li><a href="#compile">Compiling the LLVM Suite Source Code</a>
- <li><a href="#cross-compile">Cross-Compiling LLVM</a>
- <li><a href="#objfiles">The Location of LLVM Object Files</a>
- <li><a href="#optionalconfig">Optional Configuration Items</a>
+ <li><a href="#terminology">Terminology and Notation</a></li>
+ <li><a href="#environment">Setting Up Your Environment</a></li>
+ <li><a href="#unpack">Unpacking the LLVM Archives</a></li>
+ <li><a href="#checkout">Checkout LLVM from Subversion</a></li>
+ <li><a href="#installcf">Install the GCC Front End</a></li>
+ <li><a href="#config">Local LLVM Configuration</a></li>
+ <li><a href="#compile">Compiling the LLVM Suite Source Code</a></li>
+ <li><a href="#cross-compile">Cross-Compiling LLVM</a></li>
+ <li><a href="#objfiles">The Location of LLVM Object Files</a></li>
+ <li><a href="#optionalconfig">Optional Configuration Items</a></li>
</ol></li>
<li><a href="#layout">Program layout</a>
<ol>
- <li><a href="#examples"><tt>llvm/examples</tt></a>
- <li><a href="#include"><tt>llvm/include</tt></a>
- <li><a href="#lib"><tt>llvm/lib</tt></a>
- <li><a href="#projects"><tt>llvm/projects</tt></a>
- <li><a href="#runtime"><tt>llvm/runtime</tt></a>
- <li><a href="#test"><tt>llvm/test</tt></a>
- <li><a href="#llvmtest"><tt>llvm-test</tt></a>
- <li><a href="#tools"><tt>llvm/tools</tt></a>
- <li><a href="#utils"><tt>llvm/utils</tt></a>
- <li><a href="#win32"><tt>llvm/win32</tt></a>
+ <li><a href="#examples"><tt>llvm/examples</tt></a></li>
+ <li><a href="#include"><tt>llvm/include</tt></a></li>
+ <li><a href="#lib"><tt>llvm/lib</tt></a></li>
+ <li><a href="#projects"><tt>llvm/projects</tt></a></li>
+ <li><a href="#runtime"><tt>llvm/runtime</tt></a></li>
+ <li><a href="#test"><tt>llvm/test</tt></a></li>
+ <li><a href="#llvmtest"><tt>llvm-test</tt></a></li>
+ <li><a href="#tools"><tt>llvm/tools</tt></a></li>
+ <li><a href="#utils"><tt>llvm/utils</tt></a></li>
+ <li><a href="#win32"><tt>llvm/win32</tt></a></li>
</ol></li>
<li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
<p>First, LLVM comes in two pieces. The first piece is the LLVM suite. This
contains all of the tools, libraries, and header files needed to use the low
-level virtual machine. It contains an assembler, disassembler, bytecode
-analyzer and bytecode optimizer. It also contains a test suite that can be
+level virtual machine. It contains an assembler, disassembler, bitcode
+analyzer and bitcode optimizer. It also contains a test suite that can be
used to test the LLVM tools and the GCC front end.</p>
<p>The second piece is the GCC front end. This component provides a version of
-GCC that compiles C and C++ code into LLVM bytecode. Currently, the GCC front
+GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front
end uses the GCC parser to convert code to LLVM. Once
-compiled into LLVM bytecode, a program can be manipulated with the LLVM tools
+compiled into LLVM bitcode, a program can be manipulated with the LLVM tools
from the LLVM suite.</p>
<p>
<li>Read the documentation.</li>
<li>Read the documentation.</li>
<li>Remember that you were warned twice about reading the documentation.</li>
- <li>Install the GCC front end if you intend to compile C or C++:
+ <li>Install the llvm-gcc4.0 (or llvm-gcc4.2) front end if you intend to compile C or C++:
<ol>
<li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li>
<li><tt>gunzip --stdout llvm-gcc.<i>platform</i>.tar.gz | tar -xvf -</tt>
</li>
- <li><tt>cd llvm-gcc3.4/<i>platform</i> (llvm-gcc3.4 only)<br>
- ./fixheaders</tt></li>
+ <ul><li>If the binary extension is ".bz" use bunzip2 instead of gunzip.</li>
+ </ul>
<li>Add llvm-gcc's "bin" directory to your PATH variable.</li>
</ol></li>
<p>The LLVM suite <i>may</i> compile on other platforms, but it is not
guaranteed to do so. If compilation is successful, the LLVM utilities should be
-able to assemble, disassemble, analyze, and optimize LLVM bytecode. Code
+able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code
generation should work as well, although the generated native code may not work
on your platform.</p>
<li><b>date</b> - print the current date/time </li>
<li><b>echo</b> - print to standard output</li>
<li><b>egrep</b> - extended regular expression search utility</li>
- <li><b>etags</b> - C/C++ tag file creator for vim/emacs</li>
<li><b>find</b> - find files/dirs in a file system</li>
<li><b>grep</b> - regular expression search utility</li>
<li><b>gzip*</b> - gzip command for distribution generation</li>
possibly others) does not compile LLVM correctly (it appears that exception
handling is broken in some cases). Please download the FSF 3.3.3 or upgrade
to a newer version of GCC.</p>
-<p><b>GCC 3.4.0</b> on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+<p><b>GCC 3.4.0 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
code generator, causing an infinite loop in the llvm-gcc build when built
with optimizations enabled (i.e. a release build).</p>
-<p><b>GCC 3.4.2</b> on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
+<p><b>GCC 3.4.2 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
code generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0)
correctly compiles LLVM at -O2. A work around is to build release LLVM
builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."</p>
-<p><b>GCC 3.4.x
</b> on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056">
+<p><b>GCC 3.4.x on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056">
miscompiles portions of LLVM</a>.</p>
+<p><b>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</b>: this compiler miscompiles LLVM
+ when building with optimizations enabled. It appears to work with
+ "<tt>make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1</tt>" or build a debug
+ build.</p>
<p><b>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to
miscompile LLVM.</p>
<p><b>Apple Xcode 2.3</b>: GCC crashes when compiling LLVM at -O3 (which is the
variables.
<dl>
- <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bytecode/libs</tt></dt>
+ <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bitcode/libs</tt></dt>
<dd>[Optional] This environment variable helps LLVM linking tools find the
- locations of your bytecode libraries. It is provided only as a
+ locations of your bitcode libraries. It is provided only as a
convenience since you can specify the paths using the -L options of the
- tools and the C/C++ front-end will automatically use the bytecode files
+ tools and the C/C++ front-end will automatically use the bitcode files
installed in its
<tt>lib</tt> directory.</dd>
</dl>
test directories, and local copies of documentation files.</p>
<p>If you want to get a specific release (as opposed to the most recent
-revision), you can specify a label. The following releases have the following
-labels:</p>
+revision), you can checkout it from the '<tt>tags</tt>' directory (instead of
+'<tt>trunk</tt>'). The following releases are located in the following
+ subdirectories of the '<tt>tags</tt>' directory:</p>
<ul>
+<li>Release 2.1: <b>RELEASE_21</b></li>
<li>Release 2.0: <b>RELEASE_20</b></li>
<li>Release 1.9: <b>RELEASE_19</b></li>
<li>Release 1.8: <b>RELEASE_18</b></li>
<p>If you would like to get the LLVM test suite (a separate package as of 1.4),
you get it from the Subversion repository:</p>
+
+<div class="doc_code">
<pre>
- cd llvm/projects
- svn so http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
+% cd llvm/projects
+% svn co http://llvm.org/svn/llvm-project/test-suite/trunk llvm-test
</pre>
+</div>
+
<p>By placing it in the <tt>llvm/projects</tt>, it will be automatically
configured by the LLVM configure script as well as automatically updated when
you run <tt>svn update</tt>.</p>
<p>To configure LLVM, follow these steps:</p>
<ol>
- <li>Change directory into the object root directory:
- <br>
- <tt>cd <i>OBJ_ROOT</i></tt>
- <br><br>
+ <li><p>Change directory into the object root directory:</p>
- <li>Run the <tt>configure</tt> script located in the LLVM source tree:
- <br>
- <tt><i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</tt>
- <br><br>
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
+
+ <li><p>Run the <tt>configure</tt> script located in the LLVM source
+ tree:</p>
+
+ <div class="doc_code">
+ <pre>% <i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</pre>
+ </div></li>
</ol>
</div>
<p>Once you have LLVM configured, you can build it by entering the
<i>OBJ_ROOT</i> directory and issuing the following command:</p>
-<p><tt>gmake</tt></p>
+<div class="doc_code"><pre>% gmake</pre></div>
<p>If the build fails, please <a href="#brokengcc">check here</a> to see if you
are using a version of GCC that is known not to compile LLVM.</p>
the parallel build options provided by GNU Make. For example, you could use the
command:</p>
-<p><tt>gmake -j2</tt></p>
+<div class="doc_code"><pre>% gmake -j2</pre></div>
<p>There are several special targets which are useful when working with the LLVM
source code:</p>
<dt><tt>gmake -C runtime install-bytecode</tt>
<dd>
Assuming you built LLVM into $OBJDIR, when this command is run, it will
- install bytecode libraries into the GCC front end's bytecode library
- directory. If you need to update your bytecode libraries,
+ install bitcode libraries into the GCC front end's bitcode library
+ directory. If you need to update your bitcode libraries,
this is the target to use once you've built them.
<br><br>
</dl>
<ul>
<li><p>Change directory to where the LLVM object files should live:</p>
- <p><tt>cd <i>OBJ_ROOT</i></tt></p></li>
+ <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
<li><p>Run the <tt>configure</tt> script found in the LLVM source
directory:</p>
- <p><tt><i>SRC_ROOT</i>/configure</tt></p></li>
+ <div class="doc_code"><pre>% <i>SRC_ROOT</i>/configure</pre></div></li>
</ul>
<p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
<p>
If you're running on a Linux system that supports the "<a
- href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">
- binfmt_misc</a>"
+href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>"
module, and you have root access on the system, you can set your system up to
-execute LLVM bytecode files directly. To do this, use commands like this (the
+execute LLVM bitcode files directly. To do this, use commands like this (the
first command may not be required if you are already using the module):</p>
<div class="doc_code">
<pre>
- $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
- $ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
- $ chmod u+x hello.bc (if needed)
- $ ./hello.bc
+$ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+$ echo ':llvm:M::llvm::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+$ chmod u+x hello.bc (if needed)
+$ ./hello.bc
</pre>
</div>
<p>
-This allows you to execute LLVM bytecode files directly. Thanks to Jack
+This allows you to execute LLVM bitcode files directly. Thanks to Jack
Cummings for pointing this out!
</p>
<dd>This directory holds the source code for the LLVM assembly language parser
library.</dd>
- <dt><tt><b>llvm/lib/ByteCode/</b></tt></dt>
- <dd>This directory holds code for reading and write LLVM bytecode.</dd>
+ <dt><tt><b>llvm/lib/BitCode/</b></tt></dt>
+ <dd>This directory holds code for reading and write LLVM bitcode.</dd>
<dt><tt><b>llvm/lib/Analysis/</b></tt><dd>This directory contains a variety of
different program analyses, such as Dominator Information, Call Graphs,
source code locations at which the program is executing.</dd>
<dt><tt><b>llvm/lib/ExecutionEngine/</b></tt></dt>
- <dd> This directory contains libraries for executing LLVM bytecode directly
+ <dd> This directory contains libraries for executing LLVM bitcode directly
at runtime in both interpreted and JIT compiled fashions.</dd>
<dt><tt><b>llvm/lib/Support/</b></tt></dt>
<div class="doc_subsection"><a name="runtime"><tt>llvm/runtime</tt></a></div>
<div class="doc_text">
-<p>This directory contains libraries which are compiled into LLVM bytecode and
+<p>This directory contains libraries which are compiled into LLVM bitcode and
used when linking programs with the GCC front end. Most of these libraries are
skeleton versions of real libraries; for example, libc is a stripped down
version of glibc.</p>
be configured to utilize both LLVM and non-LLVM compilation tools to enable
pre-processing, translation, optimization, assembly, and linking of programs
all from one command line. <tt>llvmc</tt> also takes care of processing the
- dependent libraries found in bytecode. This reduces the need to get the
+ dependent libraries found in bitcode. This reduces the need to get the
traditional <tt>-l<name></tt> options right on the command line. Please
note that this tool, while functional, is still experimental and not feature
complete.</dd>
<dt><tt><b>llvm-ar</b></tt></dt>
<dd>The archiver produces an archive containing
- the given LLVM bytecode files, optionally with an index for faster
+ the given LLVM bitcode files, optionally with an index for faster
lookup.</dd>
<dt><tt><b>llvm-as</b></tt></dt>
<dd>The assembler transforms the human readable LLVM assembly to LLVM
- bytecode.</dd>
+ bitcode.</dd>
<dt><tt><b>llvm-dis</b></tt></dt>
- <dd>The disassembler transforms the LLVM bytecode to human readable
+ <dd>The disassembler transforms the LLVM bitcode to human readable
LLVM assembly.</dd>
<dt><tt><b>llvm-ld</b></tt></dt>
<dt><tt><b>lli</b></tt></dt>
<dd><tt>lli</tt> is the LLVM interpreter, which
- can directly execute LLVM bytecode (although very slowly...). In addition
- to a simple interpreter, <tt>lli</tt> also has a tracing mode (entered by
- specifying <tt>-trace</tt> on the command line). Finally, for
- architectures that support it (currently x86, Sparc, and PowerPC), by default,
- <tt>lli</tt> will function as a Just-In-Time compiler (if the
- functionality was compiled in), and will execute the code <i>much</i>
- faster than the interpreter.</dd>
+ can directly execute LLVM bitcode (although very slowly...). For architectures
+ that support it (currently x86, Sparc, and PowerPC), by default, <tt>lli</tt>
+ will function as a Just-In-Time compiler (if the functionality was compiled
+ in), and will execute the code <i>much</i> faster than the interpreter.</dd>
<dt><tt><b>llc</b></tt></dt>
<dd> <tt>llc</tt> is the LLVM backend compiler, which
- translates LLVM bytecode to a native code assembly file or to C code (with
+ translates LLVM bitcode to a native code assembly file or to C code (with
the -march=c option).</dd>
<dt><tt><b>llvm-gcc</b></tt></dt>
<dd><tt>llvm-gcc</tt> is a GCC-based C frontend that has been retargeted to
use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM
- byte code or assembly (with the <tt>-emit-llvm</tt> option) instead of the
+ bitcode or assembly (with the <tt>-emit-llvm</tt> option) instead of the
usual machine code output. It works just like any other GCC compiler,
taking the typical <tt>-c, -S, -E, -o</tt> options that are typically used.
Additionally, the the source code for <tt>llvm-gcc</tt> is available as a
separate Subversion module.</dd>
<dt><tt><b>opt</b></tt></dt>
- <dd><tt>opt</tt> reads LLVM bytecode, applies a series of LLVM to LLVM
+ <dd><tt>opt</tt> reads LLVM bitcode, applies a series of LLVM to LLVM
transformations (which are specified on the command line), and then outputs
- the resultant bytecode. The '<tt>opt --help</tt>' command is a good way to
+ the resultant bitcode. The '<tt>opt --help</tt>' command is a good way to
get a list of the program transformations available in LLVM.<br/>
<dd><tt>opt</tt> can also be used to run a specific analysis on an input
- LLVM bytecode file and print out the results. It is primarily useful for
+ LLVM bitcode file and print out the results. It is primarily useful for
debugging analyses, or familiarizing yourself with what an analysis does.</dd>
</dl>
</div>
<p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b>
from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b>
-create bytecode by default: <i>gcc4</i> produces native code. As the example below illustrates,
-the '--emit-llvm' flag is needed to produce LLVM bytecode output. For <i>makefiles</i> and
-<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bytecode
+create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates,
+the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and
+<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode
output.</p>
</div>
<div class="doc_text">
<ol>
- <li>First, create a simple C file, name it 'hello.c':
- <pre>
- #include <stdio.h>
- int main() {
- printf("hello world\n");
- return 0;
- }
- </pre></li>
+ <li><p>First, create a simple C file, name it 'hello.c':</p>
+
+<div class="doc_code">
+<pre>
+#include <stdio.h>
+
+int main() {
+ printf("hello world\n");
+ return 0;
+}
+</pre></div></li>
<li><p>Next, compile the C file into a native executable:</p>
- <p><tt>% llvm-gcc hello.c -o hello</tt></p>
+ <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div>
<p>Note that llvm-gcc works just like GCC by default. The standard -S and
-c arguments work as usual (producing a native .s or .o file,
- respectively). </p>
+ respectively).</p></li>
- <li><p>Next, compile the C file into a LLVM bytecode file:</p>
- <p><tt>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</tt></p>
+ <li><p>Next, compile the C file into a LLVM bitcode file:</p>
+
+ <div class="doc_code">
+ <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div>
<p>The -emit-llvm option can be used with the -S or -c options to emit an
LLVM ".ll" or ".bc" file (respectively) for the code. This allows you
to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on
- the bytecode file.</p>
+ the bitcode file.</p>
<p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments.
</p></li>
<li><p>Run the program in both forms. To run the program, use:</p>
- <p><tt>% ./hello</tt></p>
+ <div class="doc_code"><pre>% ./hello</pre></div>
<p>and</p>
- <p><tt>% lli hello.bc</tt></p>
+ <div class="doc_code"><pre>% lli hello.bc</pre></div>
<p>The second examples shows how to invoke the LLVM JIT, <a
href="CommandGuide/html/lli.html">lli</a>.</p></li>
<li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
code:</p>
- <p><tt>% llvm-dis < hello.bc | less</tt><br><br></li>
+<div class="doc_code">
+<pre>llvm-dis < hello.bc | less</pre>
+</div></li>
<li><p>Compile the program to native assembly using the LLC code
generator:</p>
- <p><tt>% llc hello.bc -o hello.s</tt></p>
+ <div class="doc_code"><pre>% llc hello.bc -o hello.s</pre></div></li>
<li><p>Assemble the native assembly language file into a program:</p>
- <p><b>Solaris:</b><tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native</tt></p>
- <p><b>Others:</b><tt>% gcc hello.s -o hello.native</tt></p>
+<div class="doc_code">
+<pre>
+<b>Solaris:</b> % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+
+<b>Others:</b> % gcc hello.s -o hello.native
+</pre>
+</div></li>
<li><p>Execute the native code program:</p>
- <p><tt>% ./hello.native</tt></p>
+ <div class="doc_code"><pre>% ./hello.native</pre></div>
<p>Note that using llvm-gcc to compile directly to native code (i.e. when
the -emit-llvm option is not present) does steps 6/7/8 for you.</p>
projects / oota-llvm.git / blobdiff