| <!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 <a |
| href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers |
| Mailing List</a>. |
| |
| <hr> |
| <address><a href="mailto:criswell@uiuc.edu">John Criswell</a></address><br> |
| <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br> |
| Last modified: $Date$ |
| |
| </body> |
| </html> |