-
-
- 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 environment variables.
-
- There are several environment variables that a Makefile needs to set to
- use the LLVM build system:
-
-
LLVM_SRC_ROOT
-
- The root of the LLVM source tree.
-
-
-
LLVM_OBJ_ROOT
-
- The root of the LLVM object tree.
-
-
-
BUILD_SRC_ROOT
-
- The root of the project's source tree.
-
-
-
BUILD_OBJ_ROOT
-
- The root of the project's object tree.
-
-
-
BUILD_SRC_DIR
-
- The directory containing the current source to be compiled.
-
-
-
BUILD_OBJ_DIR
-
- The directory where the current source will place the new object
- files. This should always be the current directory.
-
-
-
LEVEL
-
- The relative path from the current directory to the root of the
- object tree.
-
-
-
-
Include the LLVM Makefile.config from $(LLVM_OBJ_ROOT).
-
-
-
Include the LLVM 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 off of 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.
-
-
-
- Follow these simple steps to start your project:
-
-
-
- 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.
-
-
-
- Add your source code and Makefiles to your source tree.
-
-
-
- If you want your Makefiles to be configured by the
- configure script, or if you want to support multiple
- object directories, add your Makefiles to the configure
- script by adding them into the autoconf/configure.ac file.
- The macro AC_CONFIG_MAKEFILE will copy a file, unmodified,
- from the source directory to the object directory.
-
-
- After updating autoconf/configure.ac, regenerate the
- configure script with these commands:
-
-
- cd autoconf
- autoconf -o ../configure
-
-
-
-
- You must be using Autoconf version 2.57 or higher.
-
-
-
- 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.
-
-
-
- That's it! Now all you have to do is type gmake 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 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:
-
-
- LLVM provides several QMTest test classes that can be used to
- create tests. They can be found in
- llvm/test/QMTest/llvm.py. These test classes perform a
- variety of functions, including code optimization tests, assembly
- tests, and code analysis tests. The Makefile in
- llvm/test provides the QMTest context needed by LLVM test
- classes.
-
-
-
- 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 llvm/test/Programs directory.
-
- Currently, there is no way to hook your tests directly into the
- llvm/test/Programs 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:
-
-
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. 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.
-
-
-
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.
-
- Note that this works only for statically linked libraries.
-
-
-
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
-
-
-
-
Miscellaneous Variables
-
-
ExtraSource
-
- 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.
-
-
-
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 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
- BUILD_OBJ_ROOT/lib/<type>, where type is Debug,
- Release, or Profile for a debug, optimized, or
- profiled build, respectively.
-
-
-
Executables
-
- All executables will be stored in BUILD_OBJ_ROOT/lib/<type>,
- 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 (llvmdev@cs.uiuc.edu).
-
+
+
+ Creating an LLVM Project
+
+
+
+
+
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 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.
+
+
+
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 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.
