-
-
- In order to set up a new project that uses the LLVM build system,
- libraries, and header files, follow these steps:
-
-
-
- Copy the llvm/projects/sample directory to any place
- of your choosing. You can place it anywhere you like, although
- someplace underneath your home directory would work best.
-
-
-
- Edit the Makefile.config and Makefile.common
- 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.
-
-
-
- For example, if the LLVM source tree is in
- /usr/home/joe/src/llvm, and you built LLVM in
- /tmp/llvmobj, then
- LLVM_SRC_ROOT=/usr/home/joe/src/llvm and
- LLVM_OBJ_ROOT=/tmp/llvmobj.
-
-
-
- Add your source code to your source tree.
-
-
-
- Modify the various Makefiles to contain the names of the
- objects that you want to build.
-
-
-
- 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 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 good place for these 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.
-
-
- Typically, you will want to build your lib directory first
- followed by your tools directory.
-
-
-
-
- The LLVM build system provides several variables which you may
- use.
-
-
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. However, if you set the BUILD_ARCHIVE
- variable, an archive library (sometimes known as a static
- library) will be built instead.
-
-
-
SHARED_LIBRARY
-
- If SHARED_LIBRARY is defined in your Makefile, then the
- Makefiles will generate a shared (or dynamic) library.
-
-
-
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 either
- be LLVM libraries or libraries that come from your lib
- directory. The libraries must be specified by their base name.
- For example, to link libsample.a, you would set USEDLIBS to
- sample.
-
-
-
-
Miscellaneous Variables
-
-
ExtraSource
-
- 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.
-
-
-
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 these variable as
- opposed to overwriting them. The master Makefiles may already
- have useful options in them that you may not want to overwrite.
-
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.
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:
+
+
+
% 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.
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 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
+ 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.
+ 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.
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:
+ 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 "../..".
+
+ 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.
+
+ 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.
+
+ 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 -l<library base name> 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:
+
+
+ LIBS += -lsample
+
+
+ Note that LIBS must occur in the Makefile after the inclusion of Makefile.common.
+
+ 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.
+
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.
+
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.