mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-23 19:23:23 +01:00
490 lines
16 KiB
HTML
490 lines
16 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>Creating an LLVM Project</title>
|
|
<link rel="stylesheet" href="llvm.css" type="text/css">
|
|
</head>
|
|
<body>
|
|
|
|
<h1>Creating an LLVM Project</h1>
|
|
|
|
<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>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2><a name="overview">Overview</a></h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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 <tt>make</tt> variables. There are several variables that a Makefile
|
|
needs to set to use the LLVM build system:
|
|
<ul>
|
|
<li><tt>PROJECT_NAME</tt> - The name by which your project is known.</li>
|
|
<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>PROJ_SRC_ROOT</tt> - The root of the project's source tree.</li>
|
|
<li><tt>PROJ_OBJ_ROOT</tt> - The root of the project's object tree.</li>
|
|
<li><tt>PROJ_INSTALL_ROOT</tt> - The root installation directory.</li>
|
|
<li><tt>LEVEL</tt> - The relative path from the current directory to the
|
|
project's root ($PROJ_OBJ_ROOT).</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 on 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>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2>
|
|
<a name="create">Create a Project from the Sample Project</a>
|
|
</h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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>
|
|
If you downloaded LLVM using Subversion, remove all the directories named .svn
|
|
(and all the files therein) from your project's new source tree. This will
|
|
keep Subversion from thinking that your project is inside
|
|
<tt>llvm/trunk/projects/sample</tt>.</li>
|
|
|
|
<li>Add your source code and Makefiles to your source tree.</li>
|
|
|
|
<li>If you want your project to be configured with the <tt>configure</tt> script
|
|
then you need to edit <tt>autoconf/configure.ac</tt> as follows:
|
|
<ul>
|
|
<li><b>AC_INIT</b>. Place the name of your project, its version number and
|
|
a contact email address for your project as the arguments to this macro</li>
|
|
<li><b>AC_CONFIG_AUX_DIR</b>. If your project isn't in the
|
|
<tt>llvm/projects</tt> directory then you might need to adjust this so that
|
|
it specifies a relative path to the <tt>llvm/autoconf</tt> directory.</li>
|
|
<li><b>LLVM_CONFIG_PROJECT</b>. Just leave this alone.</li>
|
|
<li><b>AC_CONFIG_SRCDIR</b>. Specify a path to a file name that identifies
|
|
your project; or just leave it at <tt>Makefile.common.in</tt></li>
|
|
<li><b>AC_CONFIG_FILES</b>. Do not change.</li>
|
|
<li><b>AC_CONFIG_MAKEFILE</b>. Use one of these macros for each Makefile
|
|
that your project uses. This macro arranges for your makefiles to be copied
|
|
from the source directory, unmodified, to the build directory.</li>
|
|
</ul>
|
|
</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>
|
|
% ./AutoRegen.sh</tt></p>
|
|
</div>
|
|
|
|
<p>You must be using Autoconf version 2.59 or later and your aclocal version
|
|
should be 1.9 or later.</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></dt>
|
|
<dd>Tell your project where the LLVM source tree is located.</dd>
|
|
<dt><br><tt>--with-llvmobj=<directory></tt></dt>
|
|
<dd>Tell your project where the LLVM object tree is located.</dd>
|
|
<dt><br><tt>--prefix=<directory></tt></dt>
|
|
<dd>Tell your project where it should get installed.</dd>
|
|
</dl>
|
|
</ol>
|
|
|
|
<p>That's it! Now all you have to do is type <tt>gmake</tt> (or <tt>make</tt>
|
|
if your on a GNU/Linux system) in the root of your object directory, and your
|
|
project should build.</p>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2>
|
|
<a name="source">Source Tree Layout</a>
|
|
</h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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 basic support for tests.
|
|
The LLVM system provides the following:
|
|
<ul>
|
|
<li>
|
|
LLVM provides a tcl procedure that is used by Dejagnu to run
|
|
tests. It can be found in <tt>llvm/lib/llvm-dg.exp</tt>. This
|
|
test procedure uses RUN lines in the actual test case to determine
|
|
how to run the test. See the <a
|
|
href="TestingGuide.html">TestingGuide</a> for more details. You
|
|
can easily write Makefile support similar to the Makefiles in
|
|
<tt>llvm/test</tt> to use Dejagnu to run your project's tests.<br></li>
|
|
<li>
|
|
LLVM contains an optional package called <tt>llvm-test</tt>
|
|
which provides benchmarks and programs that 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.
|
|
<br>Currently, there is no way to hook your tests directly into the
|
|
<tt>llvm/test</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>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2>
|
|
<a name="makefiles">Writing LLVM Style Makefiles</a>
|
|
</h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h3>
|
|
<a name="reqVars">Required Variables</a>
|
|
</h3>
|
|
|
|
<div>
|
|
|
|
<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>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h3>
|
|
<a name="varsBuildDir">Variables for Building Subdirectories</a>
|
|
</h3>
|
|
|
|
<div>
|
|
|
|
<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>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h3>
|
|
<a name="varsBuildLib">Variables for Building Libraries</a>
|
|
</h3>
|
|
|
|
<div>
|
|
|
|
<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>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h3>
|
|
<a name="varsBuildProg">Variables for Building Programs</a>
|
|
</h3>
|
|
|
|
<div>
|
|
|
|
<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 be libraries that
|
|
come from your <b>lib</b> directory. The libraries must be
|
|
specified without their "lib" prefix. For example, to link
|
|
libsample.a, you would set USEDLIBS to
|
|
<tt>sample.a</tt>.
|
|
<p>
|
|
Note that this works only for statically linked libraries.
|
|
<p>
|
|
|
|
<dt>LLVMLIBS
|
|
<dd>
|
|
This variable holds a space separated list of libraries that should
|
|
be linked into the program. These libraries must be LLVM libraries.
|
|
The libraries must be specified without their "lib" prefix. For
|
|
example, to link with a driver that performs an IR transformation
|
|
you might set LLVMLIBS to this minimal set of libraries
|
|
<tt>LLVMSupport.a LLVMCore.a LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a LLVMScalarOpts.a LLVMTarget.a</tt>.
|
|
<p>
|
|
Note that this works only for statically linked libraries. LLVM is
|
|
split into a large number of static libraries, and the list of libraries you
|
|
require may be much longer than the list above. To see a full list
|
|
of libraries use:
|
|
<tt>llvm-config --libs all</tt>.
|
|
Using LINK_COMPONENTS as described below, obviates the need to set LLVMLIBS.
|
|
<p>
|
|
|
|
<dt>LINK_COMPONENTS
|
|
<dd>This variable holds a space separated list of components that
|
|
the LLVM Makefiles pass to the <tt>llvm-config</tt> tool to generate
|
|
a link line for the program. For example, to link with all LLVM
|
|
libraries use
|
|
<tt>LINK_COMPONENTS = all</tt>.
|
|
<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>
|
|
<p>
|
|
Note that LIBS must occur in the Makefile after the inclusion of Makefile.common.
|
|
<p>
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h3>
|
|
<a name="miscVars">Miscellaneous Variables</a>
|
|
</h3>
|
|
|
|
<div>
|
|
|
|
<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>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2>
|
|
<a name="objcode">Placement of Object Code</a>
|
|
</h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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>PROJ_OBJ_ROOT/<type>/lib</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>PROJ_OBJ_ROOT/<type>/bin</tt>, where type is <tt>Debug</tt>,
|
|
<tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
|
|
build, respectively.
|
|
</dl>
|
|
|
|
</div>
|
|
|
|
<!-- *********************************************************************** -->
|
|
<h2>
|
|
<a name="help">Further Help</a>
|
|
</h2>
|
|
<!-- *********************************************************************** -->
|
|
|
|
<div>
|
|
|
|
<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-blue" alt="Valid CSS"></a>
|
|
<a href="http://validator.w3.org/check/referer"><img
|
|
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
|
|
|
|
<a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
|
|
<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
|
|
<br>
|
|
Last modified: $Date$
|
|
</address>
|
|
|
|
</body>
|
|
</html>
|