This document provides usage information about the LLVM makefile
system. While loosely patterned after the BSD makefile system, LLVM has taken
a departure from BSD in order to implement additional features needed by LLVM.
Although makefile systems such as automake were attempted at one point, it
has become clear that the features needed by LLVM and the Makefile norm are
too great to use a more limited tool. Consequently, LLVM requires simply GNU
Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy
use of the features of GNU Make so the dependency on GNU Make is firm. If
you're not familiar with make, it is recommended that you read the
GNU Makefile
Manual.

While this document is rightly part of the
LLVM Programmer's Manual, it is treated
separately here because of the volume of content and because it is often an
early source of bewilderment for new developers.

The LLVM Makefile System is the component of LLVM that is responsible for
building the software, testing it, generating distributions, checking those
distributions, installing and uninstalling, etc. It consists of a several
files throughout the source tree. These files and other general concepts are
described in this section.

The LLVM Makefile System is quite generous. It not only builds its own
software, but it can build yours too. Built into the system is knowledge of
the llvm/projects directory. Any directory under projects
that has both a configure script and a Makefile is assumed
to be a project that uses the LLVM Makefile system. Building software that
uses LLVM does not require the LLVM Makefile System nor even placement in the
llvm/projects directory. However, doing so will allow your project
to get up and running quickly by utilizing the built-in features that are used
to compile LLVM. LLVM compiles itself using the same features of the makefile
system as used for projects.

For complete details on setting up your projects configuration, simply
mimic the llvm/projects/sample project or for further details,
consult the Projects.html page.

To use the makefile system, you simply create a file named
Makefile in your directory and declare values for certain variables.
The variables and values that you select determine what the makefile system
will do. These variables enable rules and processing in the makefile system
that automatically Do The Right Thing™.

Setting variables alone is not enough. You must include into your Makefile
additional files that provide the rules of the LLVM Makefile system. The
various files involved are described in the sections that follow.

Every project must have a Makefile.config at the top of its
build directory. This file is generated by the
configure script from the pattern provided by the
Makefile.config.in file located at the top of the project's
source directory. The contents of this file depend largely on what
configuration items the project uses, however most projects can get what they
need by just relying on LLVM's configuration found in
$(LLVM_OBJ_ROOT)/Makefile.config.

This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart
of the LLVM Makefile System. It provides all the logic, dependencies, and
rules for building the targets supported by the system. What it does largely
depends on the values of makevariables that
have been set beforeMakefile.rules is included.

User Makefiles need not have comments in them unless the construction is
unusual or it does not strictly follow the rules and patterns of the LLVM
makefile system. Makefile comments are invoked with the pound (#) character.
The # character and any text following it, to the end of the line, are ignored
by make.

This section provides some examples of the different kinds of modules you
can build with the LLVM makefile system. In general, each directory you
provide will build a single object although that object may be composed of
additionally compiled components.

Only a few variable definitions are needed to build a regular library.
Normally, the makefile system will build all the software into a single
libname.o (pre-linked) object. This means the library is not
searchable and that the distinction between compilation units has been
dissolved. Optionally, you can ask for a shared library (.so), archive library
(.a) or to not have the default (relinked) library built. For example:

says to build a library named "mylib" with both a shared library
(mylib.so) and an archive library (mylib.a) version but
not to build the relinked object (mylib.o). The contents of all the
libraries produced will be the same, they are just constructed differently.
Note that you normally do not need to specify the sources involved. The LLVM
Makefile system will infer the source files from the contents of the source
directory.

The LOADABLE_MODULE=1 directive can be used in conjunction with
SHARED_LIBRARY=1 to indicate that the resulting shared library should
be openable with the dlopen function and searchable with the
dlsym function (or your operating system's equivalents). While this
isn't strictly necessary on Linux and a few other platforms, it is required
on systems like HP-UX and Darwin. You should use LOADABLE_MODULE for
any shared library that you intend to be loaded into an tool via the
-load option. See the
WritingAnLLVMPass.html document
for an example of why you might want to do this.

In some situations, it is desireable to build a single bitcode module from
a variety of sources, instead of an archive, shared library, or bitcode
library. Bitcode modules can be specified in addition to any of the other
types of libraries by defining the MODULE_NAME
variable. For example:

LIBRARYNAME = mylib
BYTECODE_LIBRARY = 1
MODULE_NAME = mymod

will build a module named mymod.bc from the sources in the
directory. This module will be an aggregation of all the bitcode modules
derived from the sources. The example will also build a bitcode archive
containing a bitcode module for each compiled source file. The difference is
subtle, but important depending on how the module or library is to be linked.

In some situations, you need to create a loadable module. Loadable modules
can be loaded into programs like opt or llc to specify
additional passes to run or targets to support. Loadable modules are also
useful for debugging a pass or providing a pass with another package if that
pass can't be included in LLVM.

LLVM provides complete support for building such a module. All you need to
do is use the LOADABLE_MODULE variable in your Makefile. For example, to
build a loadable module named MyMod that uses the LLVM libraries
LLVMSupport.a and LLVMSystem.a, you would specify:

For building executable programs (tools), you must provide the name of the
tool and the names of the libraries you wish to link with the tool. For
example:

TOOLNAME = mytool
USEDLIBS = mylib
LINK_COMPONENTS = support system

says that we are to build a tool name mytool and that it requires
three libraries: mylib, LLVMSupport.a and
LLVMSystem.a.

Note that two different variables are use to indicate which libraries are
linked: USEDLIBS and LLVMLIBS. This distinction is necessary
to support projects. LLVMLIBS refers to the LLVM libraries found in
the LLVM object directory. USEDLIBS refers to the libraries built by
your project. In the case of building LLVM tools, USEDLIBS and
LLVMLIBS can be used interchangeably since the "project" is LLVM
itself and USEDLIBS refers to the same place as LLVMLIBS.

Also note that there are two different ways of specifying a library: with a
.a suffix and without. Without the suffix, the entry refers to the
re-linked (.o) file which will include all symbols of the library.
This is useful, for example, to include all passes from a library of passes.
If the .a suffix is used then the library is linked as a searchable
library (with the -l option). In this case, only the symbols that are
unresolved at that point will be resolved from the library, if they
exist. Other (unreferenced) symbols will not be included when the .a
syntax is used. Note that in order to use the .a suffix, the library
in question must have been built with the ARCHIVE_LIBRARY option set.

Many tools will want to use the JIT features of LLVM. To do this, you
simply specify that you want an execution 'engine', and the makefiles will
automatically link in the appropriate JIT for the host or an interpreter
if none is available:

TOOLNAME = my_jit_tool
USEDLIBS = mylib
LINK_COMPONENTS = engine

Of course, any additional libraries may be listed as other components. To
get a full understanding of how this changes the linker command, it is
recommended that you:

This section describes each of the targets that can be built using the LLVM
Makefile system. Any target can be invoked from any directory but not all are
applicable to a given directory (e.g. "check", "dist" and "install" will
always operate as if invoked from the top level directory).

When you invoke make with no arguments, you are implicitly
instructing it to seek the "all" target (goal). This target is used for
building the software recursively and will do different things in different
directories. For example, in a lib directory, the "all" target will
compile source files and generate libraries. But, in a tools
directory, it will link libraries and generate executables.

This target can be invoked from anywhere within a project's directories
but always invokes the check-local target
in the project's test directory, if it exists and has a
Makefile. A warning is produced otherwise. If
TESTSUITE is defined on the make
command line, it will be passed down to the invocation of
make check-local in the test directory. The intended usage
for this is to assist in running specific suites of tests. If
TESTSUITE is not set, the implementation of check-local
should run all normal tests. It is up to the project to define what
different values for TESTSUTE will do. See the
TestingGuide for further details.

This target should be implemented by the Makefile in the project's
test directory. It is invoked by the check target elsewhere.
Each project is free to define the actions of check-local as
appropriate for that project. The LLVM project itself uses dejagnu to run a
suite of feature and regresson tests. Other projects may choose to use
dejagnu or any other testing mechanism.

This target cleans the build directory, recursively removing all things
that the Makefile builds. The cleaning rules have been made guarded so they
shouldn't go awry (via rm -f $(UNSET_VARIABLE)/* which will attempt
to erase the entire directory structure.

This target builds a distribution tarball. It first builds the entire
project using the all target and then tars up the necessary files and
compresses it. The generated tarball is sufficient for a casual source
distribution, but probably not for a release (see dist-check).

This target does the same thing as the dist target but also checks
the distribution tarball. The check is made by unpacking the tarball to a new
directory, configuring it, building it, installing it, and then verifying that
the installation results are correct (by comparing to the original build).
This target can take a long time to run but should be done before a release
goes out to make sure that the distributed tarball can actually be built into
a working release.

This target finalizes shared objects and executables and copies all
libraries, headers, executables and documentation to the directory given
with the --prefix option to configure. When completed,
the prefix directory will have everything needed to use LLVM.

The LLVM makefiles can generate complete internal documentation
for all the classes by using doxygen. By default, this feature is
not enabled because it takes a long time and generates a massive
amount of data (>100MB). If you want this feature, you must configure LLVM
with the --enable-doxygen switch and ensure that a modern version of doxygen
(1.3.7 or later) is available in your PATH. You can download
doxygen from
here.

This utility target checks to see if the Makefile in the object
directory is older than the Makefile in the source directory and
copies it if so. It also reruns the configure script if that needs to
be done and rebuilds the Makefile.config file similarly. Users may
overload this target to ensure that sanity checks are run before any
building of targets as all the targets depend on preconditions.

This utility target will force a reconfigure of LLVM or your project. It
simply runs $(PROJ_OBJ_ROOT)/config.status --recheck to rerun the
configuration tests and rebuild the configured files. This isn't generally
useful as the makefiles will reconfigure themselves whenever its necessary.

This utility target, only available when $(PROJ_OBJ_ROOT) is not
the same as $(PROJ_SRC_ROOT), will completely clean the
$(PROJ_OBJ_ROOT) directory by removing its content entirely and
reconfiguring the directory. This returns the $(PROJ_OBJ_ROOT)
directory to a completely fresh state. All content in the directory except
configured files and top-level makefiles will be lost.

This target will generate a TAGS file in the top-level source
directory. It is meant for use with emacs, XEmacs, or ViM. The TAGS file
provides an index of symbol definitions so that the editor can jump you to the
definition quickly.

This target is the opposite of the install target. It removes the
header, library and executable files from the installation directories. Note
that the directories themselves are not removed because it is not guaranteed
that LLVM is the only thing installing there (e.g. --prefix=/usr).

Variables are used to tell the LLVM Makefile System what to do and to
obtain information from it. Variables are also used internally by the LLVM
Makefile System. Variable names that contain only the upper case alphabetic
letters and underscore are intended for use by the end user. All other
variables are internal to the LLVM Makefile System and should not be relied
upon nor modified. The sections below describe how to use the LLVM Makefile
variables.

Variables listed in the table below should be set before the
inclusion of $(LEVEL)/Makefile.common.
These variables provide input to the LLVM make system that tell it what to do
for the current directory.

If set to any value, causes a relinked library (.o) not to be built. By
default, libraries are built as re-linked since most LLVM libraries are
needed in their entirety and re-linked libraries will be linked more quickly
than equivalent archive libraries.

If set to any value, causes the build to generate optimized objects,
libraries and executables. This alters the flags specified to the compilers
and linkers. Generally debugging won't be a fun experience with an optimized
build.

If set to any value, causes the build to generate both optimized and
profiled objects, libraries and executables. This alters the flags specified
to the compilers and linkers to ensure that profile data can be collected
from the tools built. Use the gprof tool to analyze the output from
the profiled tools (gmon.out).

If set to any value, causes the build to disable assertions, even if
building a release or profile build. This will exclude all assertion check
code from the build. LLVM will execute faster, but with little help when
things go wrong.

Specifies additional files that should be distributed with LLVM. All
source files, all built sources, all Makefiles, and most documentation files
will be automatically distributed. Use this variable to distribute any
files that are not automatically distributed.

When specified for building a tool, the value of this variable will be
passed to the llvm-config tool to generate a link line for the
tool. Unlike USEDLIBS and LLVMLIBS, not all libraries need
to be specified. The llvm-config tool will figure out the library
dependencies and add any libraries that are needed. The USEDLIBS
variable can still be used in conjunction with LINK_COMPONENTS so
that additional project-specific libraries can be linked with the LLVM
libraries specified by LINK_COMPONENTS

By default, shared library linking will ignore any libraries specified
with the LLVMLIBS or USEDLIBS.
This prevents shared libs from including things that will be in the LLVM
tool the shared library will be loaded into. However, sometimes it is useful
to link certain libraries into your shared library and this option enables
that feature.

If set to any value, causes the shared library being built to also be
a loadable module. Loadable modules can be opened with the dlopen() function
and searched with dlsym (or the operating system's equivalent). Note that
setting this variable without also setting SHARED_LIBRARY will have
no effect.

Specifies the name of a bitcode module to be created. A bitcode
module can be specified in conjunction with other kinds of library builds
or by itself. It constructs from the sources a single linked bitcode
file.

Specifies that the build products of the directory should not be
installed but should be built even if the install target is given.
This is handy for directories that build libraries or tools that are only
used as part of the build process, such as code generators (e.g.
tblgen).

If set to any value, causes a shared library (.so) to be built in
addition to any other kinds of libraries. Note that this option will cause
all source files to be built twice: once with options for position
independent code and once without. Use it only where you really need a
shared library.

Specifies the list of source files in the current directory to be
built. Source files of any type may be specified (programs, documentation,
config files, etc.). If not specified, the makefile system will infer the
set of source files from the files present in the current directory.

Implies VERBOSE and also tells each tool invoked to be verbose. This is
handy when you're trying to see the sub-tools invoked by each tool invoked
by the makefile. For example, this will pass -v to the GCC
compilers which causes it to print out the command lines it uses to invoke
sub-tools (compiler, assembler, linker).