Creating an LLVM Project

Overview

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 configured it with --with-objroot=/tmp when his home directory is /usr/home/joe, then LLVM_SRC_ROOT=/usr/home/joe/src/llvm and LLVM_OBJ_ROOT=/tmp/src/llvm.
Add your source code to the 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 on.
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.

Makefile Variables

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.

Caveats

Some caveats and known issues:

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.