mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-23 11:13:28 +01:00
452 lines
15 KiB
HTML
452 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Creating an LLVM Project</title>
|
|
<link rel="stylesheet" href="llvm.css" type="text/css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="doc_title">Creating an LLVM Project</div>
|
|
|
|
<ol>
|
|
<li><a href="#overview">Overview</a></li>
|
|
<li><a href="#create">Create a project from the Sample Project</a></li>
|
|
<li><a href="#source">Source tree layout</a></li>
|
|
<li><a href="#makefiles">Writing LLVM-style Makefiles</a>
|
|
<ol>
|
|
<li><a href="#reqVars">Required Variables</a></li>
|
|
<li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li>
|
|
<li><a href="#varsBuildLib">Variables for Building Libraries</a></li>
|
|
<li><a href="#varsBuildProg">Variables for Building Programs</a></li>
|
|
<li><a href="#miscVars">Miscellaneous Variables</a></li>
|
|
</ol></li>
|
|
<li><a href="#objcode">Placement of object code</a></li>
|
|
<li><a href="#help">Further help</a></li>
|
|
</ol>
|
|
|
|
<div class="doc_author">
|
|
<p>Written by John Criswell</p>
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section"><a name="overview">Overview</a></div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>The LLVM build system is designed to facilitate the building of third party
|
|
projects that use LLVM header files, libraries, and tools. In order to use
|
|
these facilities, a Makefile from a project must do the following things:</p>
|
|
|
|
<ol>
|
|
<li>Set environment variables.There are several environment variables that a
|
|
Makefile needs to set to use the LLVM build system:
|
|
|
|
<ul>
|
|
<li><tt>LLVM_SRC_ROOT</tt> - The root of the LLVM source tree.</li>
|
|
<li><tt>LLVM_OBJ_ROOT</tt> - The root of the LLVM object tree.</li>
|
|
<li><tt>BUILD_SRC_ROOT</tt> - The root of the project's source tree.</li>
|
|
<li><tt>BUILD_OBJ_ROOT</tt> - The root of the project's object tree.</li>
|
|
<li><tt>BUILD_SRC_DIR</tt> - The directory containing the current source to be
|
|
compiled.</li>
|
|
<li><tt>BUILD_OBJ_DIR</tt> - The directory where the current source will place
|
|
the new object files. This should always be the current directory.</li>
|
|
<li><tt>LEVEL</tt> - The relative path from the current directory to the root
|
|
of the object tree.</li>
|
|
</ul></li>
|
|
<li>Include <tt>Makefile.config</tt> from <tt>$(LLVM_OBJ_ROOT)</tt>.</li>
|
|
<li>Include <tt>Makefile.rules</tt> from <tt>$(LLVM_SRC_ROOT)</tt>.</li>
|
|
</ol>
|
|
|
|
<p>There are two ways that you can set all of these variables:</p>
|
|
|
|
<ol>
|
|
<li>You can write your own Makefiles which hard-code these values.</li>
|
|
|
|
<li> You can use the pre-made LLVM sample project. This sample project includes
|
|
Makefiles, a configure script that can be used to configure the location of
|
|
LLVM, and the ability to support multiple object directories from a single
|
|
source directory.</li>
|
|
</ol>
|
|
|
|
<p>This document assumes that you will base your project off of the LLVM sample
|
|
project found in <tt>llvm/projects/sample</tt>. If you want to devise your own
|
|
build system, studying the sample project and LLVM Makefiles will probably
|
|
provide enough information on how to write your own Makefiles.</p>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section">
|
|
<a name="create">Create a Project from the Sample Project</a>
|
|
</div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>Follow these simple steps to start your project:</p>
|
|
|
|
<ol>
|
|
<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
|
|
choosing. You can place it anywhere you like. Rename the directory to match
|
|
the name of your project.</li>
|
|
|
|
<li>Add your source code and Makefiles to your source tree.</li>
|
|
|
|
<li>If you want your Makefiles to be configured by the <tt>configure</tt>
|
|
script, or if you want to support multiple object directories, add your
|
|
Makefiles to the <tt>configure</tt> script by adding them into the
|
|
<tt>autoconf/configure.ac</tt> file. The macro <tt>AC_CONFIG_MAKEFILE</tt> will
|
|
copy a file, unmodified, from the source directory to the object directory.</li>
|
|
|
|
<li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
|
|
configure script with these commands:
|
|
|
|
<div class="doc_code">
|
|
<p><tt>% cd autoconf<br>
|
|
% autoconf -o ../configure</tt></p>
|
|
</div>
|
|
|
|
<p>You must be using Autoconf version 2.57 or higher.</p></li>
|
|
|
|
<li>Run <tt>configure</tt> in the directory in which you want to place
|
|
object code. Use the following options to tell your project where it
|
|
can find LLVM:
|
|
|
|
<dl>
|
|
<dt><tt>--with-llvmsrc=<directory></tt>
|
|
<dd>
|
|
Tell your project where the LLVM source tree is located.
|
|
<p>
|
|
<dt><tt>--with-llvmobj=<directory></tt>
|
|
<dd>
|
|
Tell your project where the LLVM object tree is located.
|
|
</dl>
|
|
</ol>
|
|
|
|
<p>That's it! Now all you have to do is type <tt>gmake</tt> in the root of
|
|
your object directory, and your project should build.</p>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section">
|
|
<a name="source">Source Tree Layout</a>
|
|
</div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>In order to use the LLVM build system, you will want to organize your
|
|
source code so that it can benefit from the build system's features.
|
|
Mainly, you want your source tree layout to look similar to the LLVM
|
|
source tree layout. The best way to do this is to just copy the
|
|
project tree from <tt>llvm/projects/sample</tt> and modify it to meet
|
|
your needs, but you can certainly add to it if you want.</p>
|
|
|
|
<p>Underneath your top level directory, you should have the following
|
|
directories:</p>
|
|
|
|
<dl>
|
|
<dt><b>lib</b>
|
|
<dd>
|
|
This subdirectory should contain all of your library source
|
|
code. For each library that you build, you will have one
|
|
directory in <b>lib</b> that will contain that library's source
|
|
code.
|
|
|
|
<p>
|
|
Libraries can be object files, archives, or dynamic libraries.
|
|
The <b>lib</b> directory is just a convenient place for libraries
|
|
as it places them all in a directory from which they can be linked
|
|
later.
|
|
|
|
<dt><b>include</b>
|
|
<dd>
|
|
This subdirectory should contain any header files that are
|
|
global to your project. By global, we mean that they are used
|
|
by more than one library or executable of your project.
|
|
<p>
|
|
By placing your header files in <b>include</b>, they will be
|
|
found automatically by the LLVM build system. For example, if
|
|
you have a file <b>include/jazz/note.h</b>, then your source
|
|
files can include it simply with <b>#include "jazz/note.h"</b>.
|
|
|
|
<dt><b>tools</b>
|
|
<dd>
|
|
This subdirectory should contain all of your source
|
|
code for executables. For each program that you build, you
|
|
will have one directory in <b>tools</b> that will contain that
|
|
program's source code.
|
|
<p>
|
|
|
|
<dt><b>test</b>
|
|
<dd>
|
|
This subdirectory should contain tests that verify that your code
|
|
works correctly. Automated tests are especially useful.
|
|
<p>
|
|
Currently, the LLVM build system provides little support for tests,
|
|
although some exists. Expanded support for tests will hopefully
|
|
occur in the future. In the meantime, the LLVM system does provide the
|
|
following:
|
|
<ul>
|
|
<li>
|
|
LLVM provides several QMTest test classes that can be used to
|
|
create tests. They can be found in
|
|
<tt>llvm/test/QMTest/llvm.py</tt>. These test classes perform a
|
|
variety of functions, including code optimization tests, assembly
|
|
tests, and code analysis tests. The Makefile in
|
|
<tt>llvm/test</tt> provides the QMTest context needed by LLVM test
|
|
classes.
|
|
<p>
|
|
|
|
<li>
|
|
The LLVM source tree provides benchmarks and programs which are
|
|
known to compile with the LLVM GCC front ends. You can use these
|
|
programs to test your code, gather statistics information, and
|
|
compare it to the current LLVM performance statistics. These
|
|
programs are found in the <tt>llvm/test/Programs</tt> directory.
|
|
<p>
|
|
Currently, there is no way to hook your tests directly into the
|
|
<tt>llvm/test/Programs</tt> testing harness. You will simply
|
|
need to find a way to use the source provided within that directory
|
|
on your own.
|
|
</ul>
|
|
</dl>
|
|
|
|
<p>Typically, you will want to build your <b>lib</b> directory first followed by
|
|
your <b>tools</b> directory.</p>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section">
|
|
<a name="makefiles">Writing LLVM Style Makefiles</a>
|
|
</div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>The LLVM build system provides a convenient way to build libraries and
|
|
executables. Most of your project Makefiles will only need to define a few
|
|
variables. Below is a list of the variables one can set and what they can
|
|
do:</p>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<div class="doc_subsection">
|
|
<a name="reqVars">Required Variables</a>
|
|
</div>
|
|
|
|
<div class="doc_text">
|
|
|
|
<dl>
|
|
<dt>LEVEL
|
|
<dd>
|
|
This variable is the relative path from this Makefile to the
|
|
top directory of your project's source code. For example, if
|
|
your source code is in <tt>/tmp/src</tt>, then the Makefile in
|
|
<tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<div class="doc_subsection">
|
|
<a name="varsBuildDir">Variables for Building Subdirectories</a>
|
|
</div>
|
|
|
|
<div class="doc_text">
|
|
|
|
<dl>
|
|
<dt>DIRS
|
|
<dd>
|
|
This is a space separated list of subdirectories that should be
|
|
built. They will be built, one at a time, in the order
|
|
specified.
|
|
<p>
|
|
|
|
<dt>PARALLEL_DIRS
|
|
<dd>
|
|
This is a list of directories that can be built in parallel.
|
|
These will be built after the directories in DIRS have been
|
|
built.
|
|
<p>
|
|
|
|
<dt>OPTIONAL_DIRS
|
|
<dd>
|
|
This is a list of directories that can be built if they exist,
|
|
but will not cause an error if they do not exist. They are
|
|
built serially in the order in which they are listed.
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<div class="doc_subsection">
|
|
<a name="varsBuildLib">Variables for Building Libraries</a>
|
|
</div>
|
|
|
|
<div class="doc_text">
|
|
|
|
<dl>
|
|
<dt>LIBRARYNAME
|
|
<dd>
|
|
This variable contains the base name of the library that will
|
|
be built. For example, to build a library named
|
|
<tt>libsample.a</tt>, LIBRARYNAME should be set to
|
|
<tt>sample</tt>.
|
|
<p>
|
|
|
|
<dt>BUILD_ARCHIVE
|
|
<dd>
|
|
By default, a library is a <tt>.o</tt> file that is linked
|
|
directly into a program. To build an archive (also known as
|
|
a static library), set the BUILD_ARCHIVE variable.
|
|
<p>
|
|
|
|
<dt>SHARED_LIBRARY
|
|
<dd>
|
|
If SHARED_LIBRARY is defined in your Makefile, a shared
|
|
(or dynamic) library will be built.
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<div class="doc_subsection">
|
|
<a name="varsBuildProg">Variables for Building Programs</a>
|
|
</div>
|
|
|
|
<div class="doc_text">
|
|
|
|
<dl>
|
|
<dt>TOOLNAME
|
|
<dd>
|
|
This variable contains the name of the program that will
|
|
be built. For example, to build an executable named
|
|
<tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
|
|
<p>
|
|
|
|
<dt>USEDLIBS
|
|
<dd>
|
|
This variable holds a space separated list of libraries that
|
|
should be linked into the program. These libraries must either
|
|
be LLVM libraries or libraries that come from your <b>lib</b>
|
|
directory. The libraries must be specified by their base name.
|
|
For example, to link libsample.a, you would set USEDLIBS to
|
|
<tt>sample</tt>.
|
|
<p>
|
|
Note that this works only for statically linked libraries.
|
|
<p>
|
|
|
|
<dt>LIBS
|
|
<dd>
|
|
To link dynamic libraries, add <tt>-l<library base name></tt> to
|
|
the LIBS variable. The LLVM build system will look in the same places
|
|
for dynamic libraries as it does for static libraries.
|
|
<p>
|
|
For example, to link <tt>libsample.so</tt>, you would have the
|
|
following line in your <tt>Makefile</tt>:
|
|
<p>
|
|
<tt>
|
|
LIBS += -lsample
|
|
</tt>
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<div class="doc_subsection">
|
|
<a name="miscVars">Miscellaneous Variables</a>
|
|
</div>
|
|
|
|
<div class="doc_text">
|
|
|
|
<dl>
|
|
<dt>ExtraSource
|
|
<dd>
|
|
This variable contains a space separated list of extra source
|
|
files that need to be built. It is useful for including the
|
|
output of Lex and Yacc programs.
|
|
<p>
|
|
|
|
<dt>CFLAGS
|
|
<dt>CPPFLAGS
|
|
<dd>
|
|
This variable can be used to add options to the C and C++
|
|
compiler, respectively. It is typically used to add options
|
|
that tell the compiler the location of additional directories
|
|
to search for header files.
|
|
<p>
|
|
It is highly suggested that you append to CFLAGS and CPPFLAGS as
|
|
opposed to overwriting them. The master Makefiles may already
|
|
have useful options in them that you may not want to overwrite.
|
|
<p>
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section">
|
|
<a name="objcode">Placement of Object Code</a>
|
|
</div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>The final location of built libraries and executables will depend upon
|
|
whether you do a Debug, Release, or Profile build.</p>
|
|
|
|
<dl>
|
|
<dt>Libraries
|
|
<dd>
|
|
All libraries (static and dynamic) will be stored in
|
|
<tt>BUILD_OBJ_ROOT/lib/<type></tt>, where type is <tt>Debug</tt>,
|
|
<tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
|
|
profiled build, respectively.<p>
|
|
|
|
<dt>Executables
|
|
<dd>All executables will be stored in
|
|
<tt>BUILD_OBJ_ROOT/tools/<type></tt>, where type is <tt>Debug</tt>,
|
|
<tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
|
|
build, respectively.
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<div class="doc_section">
|
|
<a name="help">Further Help</a>
|
|
</div>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div class="doc_text">
|
|
|
|
<p>If you have any questions or need any help creating an LLVM project,
|
|
the LLVM team would be more than happy to help. You can always post your
|
|
questions to the <a
|
|
href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
|
|
Mailing List</a>.</p>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<hr>
|
|
<address>
|
|
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
|
|
src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
|
|
<a href="http://validator.w3.org/check/referer"><img
|
|
src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
|
|
|
|
<a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
|
|
<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
|
|
<br>
|
|
Last modified: $Date$
|
|
</address>
|
|
|
|
</body>
|
|
</html>
|