-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
<html>
- <head>
- <title>Creating an LLVM Project</title>
- </head>
-
- <body bgcolor=white>
-
- <center><h1>Creating an LLVM Project<br></h1></center>
-
- <!--===============================================================-->
- <h2><a name="a">Overview</a><hr></h2>
- <!--===============================================================-->
-
- In order to set up a new project that uses the LLVM build system,
- libraries, and header files, follow these steps:
-
- <ol>
- <li>
- Copy the <tt>llvm/projects/sample</tt> directory to any place
- of your choosing. You can place it anywhere you like, although
- someplace underneath your home directory would work best.
- <p>
-
- <li>
- Edit the <tt>Makefile.config</tt> and <tt>Makefile.common</tt>
- files so that the LLVM_SRC_ROOT variable equals the absolute
- pathname of the LLVM source tree and LLVM_OBJ_ROOT equals the
- pathname of where LLVM was built.
-
- <p>
-
- For example, if the LLVM source tree is in
- <tt>/usr/home/joe/src/llvm</tt>, and you configured it with
- <tt>--with-objroot=/tmp</tt> when his home directory is
- <tt>/usr/home/joe</tt>, then
- LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
- LLVM_OBJ_ROOT=<tt>/tmp/src/llvm</tt>.
- <p>
-
- <li>
- Add your source code to the source tree.
- <p>
-
- <li>
- Modify the various Makefiles to contain the names of the
- objects that you want to build.
- </ol>
-
- <!--===============================================================-->
- <h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
- <!--===============================================================-->
-
- In order to use the LLVM build system, you will want to lay out 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 good place for these as it
- places them all in a directory from which they can be linked
- later on.
-
- <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.
- </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">Makefile Variables</a><hr></h2>
- <!--===============================================================-->
- The LLVM build system provides several variables which you may
- use.
-
- <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. However, if you set the BUILD_ARCHIVE
- variable, an archive library (sometimes known as a static
- library) will be built instead.
- <p>
-
- <dt>SHARED_LIBRARY
- <dd>
- If SHARED_LIBRARY is defined in your Makefile, then the
- Makefiles will generate a shared (or dynamic) library.
- </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>
- </dl>
-
- <h3> Miscellaneous Variables</h3>
- <dl compact>
- <dt>ExtraSource
- <dd>
- This variable contains a space separated list of extra source
- files that needs 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 these variable 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="Caveats">Caveats</a><hr></h2>
- <!--===============================================================-->
-
- Some caveats and known issues:
- <ol>
- <li>
- The projects system currently uses the $HOME environment
- variable in determining where object files should go. If $HOME
- is not set, then your path relative to the root directory may
- be used to determine where your object files go. It is
- therefore advised that your source directory reside underneath
- your home directory.
- </ol>
+<head>
+ <title>Creating an LLVM Project</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+<body>
+
+<div class="doc_title">Creating an LLVM Project</div>
+
+<ol>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#create">Create a project from the Sample Project</a></li>
+<li><a href="#source">Source tree layout</a></li>
+<li><a href="#makefiles">Writing LLVM-style Makefiles</a>
+ <ol>
+ <li><a href="#reqVars">Required Variables</a></li>
+ <li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li>
+ <li><a href="#varsBuildLib">Variables for Building Libraries</a></li>
+ <li><a href="#varsBuildProg">Variables for Building Programs</a></li>
+ <li><a href="#miscVars">Miscellaneous Variables</a></li>
+ </ol></li>
+<li><a href="#objcode">Placement of object code</a></li>
+<li><a href="#help">Further help</a></li>
+</ol>
+
+<div class="doc_author">
+ <p>Written by John Criswell</p>
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section"><a name="overview">Overview</a></div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>The LLVM build system is designed to facilitate the building of third party
+projects that use LLVM header files, libraries, and tools. In order to use
+these facilities, a Makefile from a project must do the following things:</p>
+
+<ol>
+ <li>Set <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>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="create">Create a Project from the Sample Project</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>Follow these simple steps to start your project:</p>
+
+<ol>
+<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
+choosing. You can place it anywhere you like. Rename the directory to match
+the name of your project.</li>
+
+<li>Add your source code and Makefiles to your source tree.</li>
+
+<li>If you want your 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_AUC_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.config.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 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>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="source">Source Tree Layout</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>In order to use the LLVM build system, you will want to organize your
+source code so that it can benefit from the build system's features.
+Mainly, you want your source tree layout to look similar to the LLVM
+source tree layout. The best way to do this is to just copy the
+project tree from <tt>llvm/projects/sample</tt> and modify it to meet
+your needs, but you can certainly add to it if you want.</p>
+
+<p>Underneath your top level directory, you should have the following
+directories:</p>
+
+<dl>
+ <dt><b>lib</b>
+ <dd>
+ This subdirectory should contain all of your library source
+ code. For each library that you build, you will have one
+ directory in <b>lib</b> that will contain that library's source
+ code.
+
+ <p>
+ Libraries can be object files, archives, or dynamic libraries.
+ The <b>lib</b> directory is just a convenient place for libraries
+ as it places them all in a directory from which they can be linked
+ later.
+
+ <dt><b>include</b>
+ <dd>
+ This subdirectory should contain any header files that are
+ global to your project. By global, we mean that they are used
+ by more than one library or executable of your project.
+ <p>
+ By placing your header files in <b>include</b>, they will be
+ found automatically by the LLVM build system. For example, if
+ you have a file <b>include/jazz/note.h</b>, then your source
+ files can include it simply with <b>#include "jazz/note.h"</b>.
+
+ <dt><b>tools</b>
+ <dd>
+ This subdirectory should contain all of your source
+ code for executables. For each program that you build, you
+ will have one directory in <b>tools</b> that will contain that
+ program's source code.
+ <p>
+
+ <dt><b>test</b>
+ <dd>
+ This subdirectory should contain tests that verify that your code
+ works correctly. Automated tests are especially useful.
+ <p>
+ Currently, the LLVM build system provides 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>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="makefiles">Writing LLVM Style Makefiles</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>The LLVM build system provides a convenient way to build libraries and
+executables. Most of your project Makefiles will only need to define a few
+variables. Below is a list of the variables one can set and what they can
+do:</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="reqVars">Required Variables</a>
+</div>
+
+<div class="doc_text">
+
+<dl>
+ <dt>LEVEL
+ <dd>
+ This variable is the relative path from this Makefile to the
+ top directory of your project's source code. For example, if
+ your source code is in <tt>/tmp/src</tt>, then the Makefile in
+ <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="varsBuildDir">Variables for Building Subdirectories</a>
+</div>
+
+<div class="doc_text">
+
+<dl>
+ <dt>DIRS
+ <dd>
+ This is a space separated list of subdirectories that should be
+ built. They will be built, one at a time, in the order
+ specified.
+ <p>
+
+ <dt>PARALLEL_DIRS
+ <dd>
+ This is a list of directories that can be built in parallel.
+ These will be built after the directories in DIRS have been
+ built.
+ <p>
+
+ <dt>OPTIONAL_DIRS
+ <dd>
+ This is a list of directories that can be built if they exist,
+ but will not cause an error if they do not exist. They are
+ built serially in the order in which they are listed.
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="varsBuildLib">Variables for Building Libraries</a>
+</div>
+
+<div class="doc_text">
+
+<dl>
+ <dt>LIBRARYNAME
+ <dd>
+ This variable contains the base name of the library that will
+ be built. For example, to build a library named
+ <tt>libsample.a</tt>, LIBRARYNAME should be set to
+ <tt>sample</tt>.
+ <p>
+
+ <dt>BUILD_ARCHIVE
+ <dd>
+ By default, a library is a <tt>.o</tt> file that is linked
+ directly into a program. To build an archive (also known as
+ a static library), set the BUILD_ARCHIVE variable.
+ <p>
+
+ <dt>SHARED_LIBRARY
+ <dd>
+ If SHARED_LIBRARY is defined in your Makefile, a shared
+ (or dynamic) library will be built.
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="varsBuildProg">Variables for Building Programs</a>
+</div>
+
+<div class="doc_text">
+
+<dl>
+ <dt>TOOLNAME
+ <dd>
+ This variable contains the name of the program that will
+ be built. For example, to build an executable named
+ <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
+ <p>
+
+ <dt>USEDLIBS
+ <dd>
+ This variable holds a space separated list of libraries that
+ should be linked into the program. These libraries must either
+ be LLVM libraries or libraries that come from your <b>lib</b>
+ directory. The libraries must be specified by their base name.
+ For example, to link libsample.a, you would set USEDLIBS to
+ <tt>sample</tt>.
+ <p>
+ Note that this works only for statically linked libraries.
+ <p>
+
+ <dt>LIBS
+ <dd>
+ To link dynamic libraries, add <tt>-l<library base name></tt> to
+ the LIBS variable. The LLVM build system will look in the same places
+ for dynamic libraries as it does for static libraries.
+ <p>
+ For example, to link <tt>libsample.so</tt>, you would have the
+ following line in your <tt>Makefile</tt>:
+ <p>
+ <tt>
+ LIBS += -lsample
+ </tt>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="miscVars">Miscellaneous Variables</a>
+</div>
+
+<div class="doc_text">
+
+<dl>
+ <dt>ExtraSource
+ <dd>
+ This variable contains a space separated list of extra source
+ files that need to be built. It is useful for including the
+ output of Lex and Yacc programs.
+ <p>
+
+ <dt>CFLAGS
+ <dt>CPPFLAGS
+ <dd>
+ This variable can be used to add options to the C and C++
+ compiler, respectively. It is typically used to add options
+ that tell the compiler the location of additional directories
+ to search for header files.
+ <p>
+ It is highly suggested that you append to CFLAGS and CPPFLAGS as
+ opposed to overwriting them. The master Makefiles may already
+ have useful options in them that you may not want to overwrite.
+ <p>
+</dl>
+
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="objcode">Placement of Object Code</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>The final location of built libraries and executables will depend upon
+whether you do a Debug, Release, or Profile build.</p>
+
+<dl>
+ <dt>Libraries
+ <dd>
+ All libraries (static and dynamic) will be stored in
+ <tt>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>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="help">Further Help</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p>If you have any questions or need any help creating an LLVM project,
+the LLVM team would be more than happy to help. You can always post your
+questions to the <a
+href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
+Mailing List</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+
+ <a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
+ <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <br>
+ Last modified: $Date$
+</address>
+
</body>
</html>