mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-23 11:13:28 +01:00
391 lines
12 KiB
HTML
391 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Creating an LLVM Project</title>
|
|
</head>
|
|
|
|
<body bgcolor=white>
|
|
|
|
<center><h1>Creating an LLVM Project<br></h1></center>
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="a">Overview</a><hr></h2>
|
|
<!--===============================================================-->
|
|
|
|
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:
|
|
|
|
<ol>
|
|
<li>Set environment variables.
|
|
<p>
|
|
There are several environment variables that a Makefile needs to set to
|
|
use the LLVM build system:
|
|
<dl compact>
|
|
<dt>LLVM_SRC_ROOT
|
|
<dd>
|
|
The root of the LLVM source tree.
|
|
<p>
|
|
|
|
<dt>LLVM_OBJ_ROOT
|
|
<dd>
|
|
The root of the LLVM object tree.
|
|
<p>
|
|
|
|
<dt>BUILD_SRC_ROOT
|
|
<dd>
|
|
The root of the project's source tree.
|
|
<p>
|
|
|
|
<dt>BUILD_OBJ_ROOT
|
|
<dd>
|
|
The root of the project's object tree.
|
|
<p>
|
|
|
|
<dt>BUILD_SRC_DIR
|
|
<dd>
|
|
The directory containing the current source to be compiled.
|
|
<p>
|
|
|
|
<dt>BUILD_OBJ_DIR
|
|
<dd>
|
|
The directory where the current source will place the new object
|
|
files. This should always be the current directory.
|
|
<p>
|
|
|
|
<dt>LEVEL
|
|
<dd>
|
|
The relative path from the current directory to the root of the
|
|
object tree.
|
|
<p>
|
|
</dl>
|
|
|
|
<li>Include the LLVM Makefile.config from $(LLVM_OBJ_ROOT).
|
|
<p>
|
|
|
|
<li>Include the LLVM Makefile.rules from $(LLVM_SRC_ROOT).
|
|
</ol>
|
|
|
|
There are two ways that you can set all of these variables:
|
|
<ol>
|
|
<li>
|
|
You can write your own Makefiles which hard-code these values.
|
|
|
|
<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.
|
|
</ol>
|
|
|
|
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>
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="a">Create a Project from the Sample Project</a><hr></h2>
|
|
<!--===============================================================-->
|
|
|
|
Follow these simple steps to start your project:
|
|
|
|
<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.
|
|
<p>
|
|
|
|
<li>
|
|
Add your source code and Makefiles to your source tree.
|
|
<p>
|
|
|
|
<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.
|
|
|
|
<p>
|
|
After updating <tt>autoconf/configure.ac</tt>, regenerate the
|
|
configure script with these commands:
|
|
<p>
|
|
<tt>
|
|
cd autoconf<br>
|
|
autoconf -o ../configure
|
|
</tt>
|
|
|
|
<p>
|
|
|
|
You must be using Autoconf version 2.57 or higher.
|
|
<p>
|
|
|
|
<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 compact>
|
|
<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>
|
|
|
|
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.
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
|
|
<!--===============================================================-->
|
|
|
|
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.
|
|
|
|
Underneath your top level directory, you should have the following
|
|
directories:
|
|
|
|
<dl compact>
|
|
<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>
|
|
|
|
Typically, you will want to build your <b>lib</b> directory first
|
|
followed by your <b>tools</b> directory.
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="Makefile Variables">Writing LLVM Style Makefiles</a><hr></h2>
|
|
<!--===============================================================-->
|
|
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:
|
|
|
|
<h3> Required Variables </h3>
|
|
<dl compact>
|
|
<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 /tmp/src, then the Makefile in
|
|
/tmp/src/jump/high would set LEVEL to "../..".
|
|
</dl>
|
|
|
|
<h3> Variables for Building Subdirectories</h3>
|
|
<dl compact>
|
|
<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>
|
|
|
|
<h3> Variables for Building Libraries</h3>
|
|
<dl compact>
|
|
<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>
|
|
|
|
<h3> Variables for Building Programs</h3>
|
|
<dl compact>
|
|
<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>
|
|
|
|
<h3> Miscellaneous Variables</h3>
|
|
<dl compact>
|
|
<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>
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="objcode">Placement of Object Code</a><hr></h2>
|
|
<!--===============================================================-->
|
|
|
|
The final location of built libraries and executables will depend upon
|
|
whether you do a Debug, Release, or Profile build.
|
|
|
|
<dl compact>
|
|
<dt>Libraries
|
|
<dd>
|
|
All libraries (static and dynamic) will be stored in
|
|
BUILD_OBJ_ROOT/lib/<type>, 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 BUILD_OBJ_ROOT/lib/<type>,
|
|
where type is <tt>Debug</tt>, <tt>Release</tt>, or <tt>Profile</tt> for
|
|
a debug, optimized, or profiled build, respectively.
|
|
</dl>
|
|
|
|
<!--===============================================================-->
|
|
<h2><a name="help">Further Help</a><hr></h2>
|
|
<!--===============================================================-->
|
|
|
|
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 (<a
|
|
href="mailto:llvmdev.cs.uiuc.edu">llvmdev@cs.uiuc.edu</a>).
|
|
|
|
<hr>
|
|
Written by <a href="mailto:criswell@uiuc.edu">John Criswell</a>.
|
|
<br>
|
|
<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
|
|
<br>
|
|
</body>
|
|
</html>
|