mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-26 04:40:38 +00:00
First attempt at Sphinx. Convert the Projects.html file to Sphinx format.
llvm-svn: 158709
This commit is contained in:
Bill Wendling
parent
960b65a03c
commit
8c5537918b
@ -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