| <!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> |
| <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> |
| 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> |
| |
| <!-- *********************************************************************** --> |
| <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-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> |