mirror of
https://github.com/c64scene-ar/llvm-6502.git
synced 2024-12-13 04:30:23 +00:00
First attempt at Sphinx. Convert the Projects.html file to Sphinx format.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@158709 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
parent
b51c8e9bb5
commit
4caaa1ab87
@ -1,482 +0,0 @@
|
|||||||
<!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="_static/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>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>
|
|
329
docs/Projects.rst
Normal file
329
docs/Projects.rst
Normal file
@ -0,0 +1,329 @@
|
|||||||
|
.. _projects:
|
||||||
|
|
||||||
|
========================
|
||||||
|
Creating an LLVM Project
|
||||||
|
========================
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
:local:
|
||||||
|
|
||||||
|
Overview
|
||||||
|
========
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
* Set ``make`` variables. There are several variables that a ``Makefile`` needs
|
||||||
|
to set to use the LLVM build system:
|
||||||
|
|
||||||
|
* ``PROJECT_NAME`` — The name by which your project is known.
|
||||||
|
* ``LLVM_SRC_ROOT`` — The root of the LLVM source tree.
|
||||||
|
* ``LLVM_OBJ_ROOT`` — The root of the LLVM object tree.
|
||||||
|
* ``PROJ_SRC_ROOT`` — The root of the project's source tree.
|
||||||
|
* ``PROJ_OBJ_ROOT`` — The root of the project's object tree.
|
||||||
|
* ``PROJ_INSTALL_ROOT`` — The root installation directory.
|
||||||
|
* ``LEVEL`` — The relative path from the current directory to the
|
||||||
|
project's root ``($PROJ_OBJ_ROOT)``.
|
||||||
|
|
||||||
|
* Include ``Makefile.config`` from ``$(LLVM_OBJ_ROOT)``.
|
||||||
|
|
||||||
|
* Include ``Makefile.rules`` from ``$(LLVM_SRC_ROOT)``.
|
||||||
|
|
||||||
|
There are two ways that you can set all of these variables:
|
||||||
|
|
||||||
|
* You can write your own ``Makefiles`` which hard-code these values.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
This document assumes that you will base your project on the LLVM sample project
|
||||||
|
found in ``llvm/projects/sample``. 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``.
|
||||||
|
|
||||||
|
Create a Project from the Sample Project
|
||||||
|
========================================
|
||||||
|
|
||||||
|
Follow these simple steps to start your project:
|
||||||
|
|
||||||
|
#. Copy the ``llvm/projects/sample`` directory to any place of your choosing.
|
||||||
|
You can place it anywhere you like. Rename the directory to match the name
|
||||||
|
of your project.
|
||||||
|
|
||||||
|
#. 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
|
||||||
|
``llvm/trunk/projects/sample``.
|
||||||
|
|
||||||
|
#. Add your source code and Makefiles to your source tree.
|
||||||
|
|
||||||
|
#. If you want your project to be configured with the ``configure`` script then
|
||||||
|
you need to edit ``autoconf/configure.ac`` as follows:
|
||||||
|
|
||||||
|
* **``AC_INIT``** — Place the name of your project, its version number
|
||||||
|
and a contact email address for your project as the arguments to this macro
|
||||||
|
|
||||||
|
* **``AC_CONFIG_AUX_DIR``** — If your project isn't in the
|
||||||
|
``llvm/projects`` directory then you might need to adjust this so that it
|
||||||
|
specifies a relative path to the ``llvm/autoconf`` directory.
|
||||||
|
|
||||||
|
* **``LLVM_CONFIG_PROJECT``** — Just leave this alone.
|
||||||
|
|
||||||
|
* **``AC_CONFIG_SRCDIR``** — Specify a path to a file name that
|
||||||
|
identifies your project; or just leave it at ``Makefile.common.in``.
|
||||||
|
|
||||||
|
* **``AC_CONFIG_FILES``** — Do not change.
|
||||||
|
|
||||||
|
* **``AC_CONFIG_MAKEFILE``** — 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.
|
||||||
|
|
||||||
|
#. After updating ``autoconf/configure.ac``, regenerate the configure script
|
||||||
|
with these commands:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
% cd autoconf
|
||||||
|
% ./AutoRegen.sh
|
||||||
|
|
||||||
|
You must be using Autoconf version 2.59 or later and your ``aclocal`` version
|
||||||
|
should be 1.9 or later.
|
||||||
|
|
||||||
|
#. Run ``configure`` in the directory in which you want to place object code.
|
||||||
|
Use the following options to tell your project where it can find LLVM:
|
||||||
|
|
||||||
|
``--with-llvmsrc=<directory>``
|
||||||
|
Tell your project where the LLVM source tree is located.
|
||||||
|
|
||||||
|
``--with-llvmobj=<directory>``
|
||||||
|
Tell your project where the LLVM object tree is located.
|
||||||
|
|
||||||
|
``--prefix=<directory>``
|
||||||
|
Tell your project where it should get installed.
|
||||||
|
|
||||||
|
That's it! Now all you have to do is type ``gmake`` (or ``make`` if your on a
|
||||||
|
GNU/Linux system) in the root of your object directory, and your project should
|
||||||
|
build.
|
||||||
|
|
||||||
|
Source Tree Layout
|
||||||
|
==================
|
||||||
|
|
||||||
|
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
|
||||||
|
``llvm/projects/sample`` and modify it to meet your needs, but you can certainly
|
||||||
|
add to it if you want.
|
||||||
|
|
||||||
|
Underneath your top level directory, you should have the following directories:
|
||||||
|
|
||||||
|
**``lib``**
|
||||||
|
|
||||||
|
This subdirectory should contain all of your library source code. For each
|
||||||
|
library that you build, you will have one directory in **``lib``** that will
|
||||||
|
contain that library's source code.
|
||||||
|
|
||||||
|
Libraries can be object files, archives, or dynamic libraries. The
|
||||||
|
**``lib``** directory is just a convenient place for libraries as it places
|
||||||
|
them all in a directory from which they can be linked later.
|
||||||
|
|
||||||
|
**``include``**
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
By placing your header files in **``include``**, they will be found
|
||||||
|
automatically by the LLVM build system. For example, if you have a file
|
||||||
|
**``include/jazz/note.h``**, then your source files can include it simply
|
||||||
|
with **``#include "jazz/note.h"``**.
|
||||||
|
|
||||||
|
**``tools``**
|
||||||
|
|
||||||
|
This subdirectory should contain all of your source code for executables.
|
||||||
|
For each program that you build, you will have one directory in
|
||||||
|
**``tools``** that will contain that program's source code.
|
||||||
|
|
||||||
|
**``test``**
|
||||||
|
|
||||||
|
This subdirectory should contain tests that verify that your code works
|
||||||
|
correctly. Automated tests are especially useful.
|
||||||
|
|
||||||
|
Currently, the LLVM build system provides basic support for tests. The LLVM
|
||||||
|
system provides the following:
|
||||||
|
|
||||||
|
* LLVM provides a ``tcl`` procedure that is used by ``Dejagnu`` to run tests.
|
||||||
|
It can be found in ``llvm/lib/llvm-dg.exp``. This test procedure uses ``RUN``
|
||||||
|
lines in the actual test case to determine how to run the test. See the
|
||||||
|
`TestingGuide`_TestingGuide.html for more details. You can easily write
|
||||||
|
Makefile support similar to the Makefiles in ``llvm/test`` to use ``Dejagnu``
|
||||||
|
to run your project's tests.
|
||||||
|
|
||||||
|
* LLVM contains an optional package called ``llvm-test``, which provides
|
||||||
|
benchmarks and programs that are known to compile with the Clang front
|
||||||
|
end. You can use these programs to test your code, gather statistical
|
||||||
|
information, and compare it to the current LLVM performance statistics.
|
||||||
|
|
||||||
|
Currently, there is no way to hook your tests directly into the ``llvm/test``
|
||||||
|
testing harness. You will simply need to find a way to use the source
|
||||||
|
provided within that directory on your own.
|
||||||
|
|
||||||
|
Typically, you will want to build your **``lib``** directory first followed by
|
||||||
|
your **``tools``** directory.
|
||||||
|
|
||||||
|
Writing LLVM Style Makefiles
|
||||||
|
============================
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
Required Variables
|
||||||
|
------------------
|
||||||
|
|
||||||
|
``LEVEL``
|
||||||
|
|
||||||
|
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 ``/tmp/src``, then the ``Makefile`` in ``/tmp/src/jump/high``
|
||||||
|
would set ``LEVEL`` to ``"../.."``.
|
||||||
|
|
||||||
|
Variables for Building Subdirectories
|
||||||
|
-------------------------------------
|
||||||
|
|
||||||
|
``DIRS``
|
||||||
|
|
||||||
|
This is a space separated list of subdirectories that should be built. They
|
||||||
|
will be built, one at a time, in the order specified.
|
||||||
|
|
||||||
|
``PARALLEL_DIRS``
|
||||||
|
|
||||||
|
This is a list of directories that can be built in parallel. These will be
|
||||||
|
built after the directories in DIRS have been built.
|
||||||
|
|
||||||
|
``OPTIONAL_DIRS``
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Variables for Building Libraries
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
``LIBRARYNAME``
|
||||||
|
|
||||||
|
This variable contains the base name of the library that will be built. For
|
||||||
|
example, to build a library named ``libsample.a``, ``LIBRARYNAME`` should
|
||||||
|
be set to ``sample``.
|
||||||
|
|
||||||
|
``BUILD_ARCHIVE``
|
||||||
|
|
||||||
|
By default, a library is a ``.o`` file that is linked directly into a
|
||||||
|
program. To build an archive (also known as a static library), set the
|
||||||
|
``BUILD_ARCHIVE`` variable.
|
||||||
|
|
||||||
|
``SHARED_LIBRARY``
|
||||||
|
|
||||||
|
If ``SHARED_LIBRARY`` is defined in your Makefile, a shared (or dynamic)
|
||||||
|
library will be built.
|
||||||
|
|
||||||
|
Variables for Building Programs
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
``TOOLNAME``
|
||||||
|
|
||||||
|
This variable contains the name of the program that will be built. For
|
||||||
|
example, to build an executable named ``sample``, ``TOOLNAME`` should be set
|
||||||
|
to ``sample``.
|
||||||
|
|
||||||
|
``USEDLIBS``
|
||||||
|
|
||||||
|
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 **``lib``** directory. The libraries must be specified without their
|
||||||
|
``lib`` prefix. For example, to link ``libsample.a``, you would set
|
||||||
|
``USEDLIBS`` to ``sample.a``.
|
||||||
|
|
||||||
|
Note that this works only for statically linked libraries.
|
||||||
|
|
||||||
|
``LLVMLIBS``
|
||||||
|
|
||||||
|
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 ``LLVMSupport.a LLVMCore.a
|
||||||
|
LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a
|
||||||
|
LLVMScalarOpts.a LLVMTarget.a``.
|
||||||
|
|
||||||
|
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: ``llvm-config --libs all``. Using ``LINK_COMPONENTS`` as
|
||||||
|
described below, obviates the need to set ``LLVMLIBS``.
|
||||||
|
|
||||||
|
``LINK_COMPONENTS``
|
||||||
|
|
||||||
|
This variable holds a space separated list of components that the LLVM
|
||||||
|
``Makefiles`` pass to the ``llvm-config`` tool to generate a link line for
|
||||||
|
the program. For example, to link with all LLVM libraries use
|
||||||
|
``LINK_COMPONENTS = all``.
|
||||||
|
|
||||||
|
``LIBS``
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
For example, to link ``libsample.so``, you would have the following line in
|
||||||
|
your ``Makefile``:
|
||||||
|
|
||||||
|
.. code-block: Makefile
|
||||||
|
|
||||||
|
LIBS += -lsample
|
||||||
|
|
||||||
|
Note that ``LIBS`` must occur in the Makefile after the inclusion of
|
||||||
|
``Makefile.common``.
|
||||||
|
|
||||||
|
Miscellaneous Variables
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
``CFLAGS``
|
||||||
|
``CPPFLAGS``
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Placement of Object Code
|
||||||
|
========================
|
||||||
|
|
||||||
|
The final location of built libraries and executables will depend upon whether
|
||||||
|
you do a ``Debug``, ``Release``, or ``Profile`` build.
|
||||||
|
|
||||||
|
Libraries
|
||||||
|
|
||||||
|
All libraries (static and dynamic) will be stored in
|
||||||
|
``PROJ_OBJ_ROOT/<type>/lib``, where *``type``* is ``Debug``, ``Release``, or
|
||||||
|
``Profile`` for a debug, optimized, or profiled build, respectively.
|
||||||
|
|
||||||
|
Executables
|
||||||
|
|
||||||
|
All executables will be stored in ``PROJ_OBJ_ROOT/<type>/bin``, where
|
||||||
|
*``type``* is ``Debug``, ``Release``, or ``Profile`` for a debug, optimized,
|
||||||
|
or profiled build, respectively.
|
||||||
|
|
||||||
|
Further Help
|
||||||
|
============
|
||||||
|
|
||||||
|
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 `LLVM Developers Mailing List`_http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev.
|
Loading…
Reference in New Issue
Block a user