This document details how to use the LLVM autotools based build system to configure and build LLVM from source. The normal developer process using CMake is detailed here.
Once checked out from the Subversion repository, the LLVM suite source code must be configured via the configure script. This script sets variables in the various *.in files, most notably llvm/Makefile.config and llvm/include/Config/config.h. It also populates OBJ_ROOT with the Makefiles needed to begin building LLVM.
The following environment variables are used by the configure script to configure the build system:
| Variable | Purpose |
|---|---|
| CC | Tells configure which C compiler to use. By default, configure will check PATH for clang and GCC C compilers (in this order). Use this variable to override configure‘s default behavior. |
| CXX | Tells configure which C++ compiler to use. By default, configure will check PATH for clang++ and GCC C++ compilers (in this order). Use this variable to override configure‘s default behavior. |
The following options can be used to set or enable LLVM specific options:
--enable-optimized
Enables optimized compilation (debugging symbols are removed and GCC optimization flags are enabled). Note that this is the default setting if you are using the LLVM distribution. The default behavior of a Subversion checkout is to use an unoptimized build (also known as a debug build).
--enable-debug-runtime
Enables debug symbols in the runtime libraries. The default is to strip debug symbols from the runtime libraries.
--enable-jit
Compile the Just In Time (JIT) compiler functionality. This is not available on all platforms. The default is dependent on platform, so it is best to explicitly enable it if you want it.
--enable-targets=target-option
Controls which targets will be built and linked into llc. The default value for target_options is “all” which builds and links all available targets. The “host” target is selected as the target of the build host. You can also specify a comma separated list of target names that you want available in llc. The target names use all lower case. The current set of targets is:
aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430, powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore.
--enable-doxygen
Look for the doxygen program and enable construction of doxygen based documentation from the source code. This is disabled by default because generating the documentation can take a long time and producess 100s of megabytes of output.
To configure LLVM, follow these steps:
Change directory into the object root directory:
% cd OBJ_ROOT
Run the configure script located in the LLVM source tree:
% $LLVM_SRC_DIR/configure --prefix=/install/path [other options]
Once you have configured LLVM, you can build it. There are three types of builds:
Debug Builds
These builds are the default when one is using a Subversion checkout and types gmake (unless the --enable-optimized option was used during configuration). The build system will compile the tools and libraries with debugging information. To get a Debug Build using the LLVM distribution the --disable-optimized option must be passed to configure.
Release (Optimized) Builds
These builds are enabled with the --enable-optimized option to configure or by specifying ENABLE_OPTIMIZED=1 on the gmake command line. For these builds, the build system will compile the tools and libraries with GCC optimizations enabled and strip debugging information from the libraries and executables it generates. Note that Release Builds are default when using an LLVM distribution.
Profile Builds
These builds are for use with profiling. They compile profiling information into the code for use with programs like gprof. Profile builds must be started by specifying ENABLE_PROFILING=1 on the gmake command line.
Once you have LLVM configured, you can build it by entering the OBJ_ROOT directory and issuing the following command:
% gmake
If the build fails, please check here to see if you are using a version of GCC that is known not to compile LLVM.
If you have multiple processors in your machine, you may wish to use some of the parallel build options provided by GNU Make. For example, you could use the command:
% gmake -j2
There are several special targets which are useful when working with the LLVM source code:
gmake clean
Removes all files generated by the build. This includes object files, generated C/C++ files, libraries, and executables.
gmake dist-clean
Removes everything that gmake clean does, but also removes files generated by configure. It attempts to return the source tree to the original state in which it was shipped.
gmake install
Installs LLVM header files, libraries, tools, and documentation in a hierarchy under $PREFIX, specified with $LLVM_SRC_DIR/configure --prefix=[dir], which defaults to /usr/local.
gmake -C runtime install-bytecode
Assuming you built LLVM into $OBJDIR, when this command is run, it will install bitcode libraries into the GCC front end’s bitcode library directory. If you need to update your bitcode libraries, this is the target to use once you’ve built them.
Please see the Makefile Guide for further details on these make targets and descriptions of other targets available.
It is also possible to override default values from configure by declaring variables on the command line. The following are some examples:
gmake ENABLE_OPTIMIZED=1
Perform a Release (Optimized) build.
gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1
Perform a Release (Optimized) build without assertions enabled.
gmake ENABLE_OPTIMIZED=0
Perform a Debug build.
gmake ENABLE_PROFILING=1
Perform a Profiling build.
gmake VERBOSE=1
Print what gmake is doing on standard output.
gmake TOOL_VERBOSE=1
Ask each tool invoked by the makefiles to print out what it is doing on the standard output. This also implies VERBOSE=1.
Every directory in the LLVM object tree includes a Makefile to build it and any subdirectories that it contains. Entering any directory inside the LLVM object tree and typing gmake should rebuild anything in or below that directory that is out of date.
This does not apply to building the documentation. LLVM’s (non-Doxygen) documentation is produced with the Sphinx documentation generation system. There are some HTML documents that have not yet been converted to the new system (which uses the easy-to-read and easy-to-write reStructuredText plaintext markup language). The generated documentation is built in the $LLVM_SRC_DIR/docs directory using a special makefile. For instructions on how to install Sphinx, see Sphinx Introduction for LLVM Developers. After following the instructions there for installing Sphinx, build the LLVM HTML documentation by doing the following:
$ cd $LLVM_SRC_DIR/docs
$ make -f Makefile.sphinx
This creates a _build/html sub-directory with all of the HTML files, not just the generated ones. This directory corresponds to llvm.org/docs. For example, _build/html/SphinxQuickstartTemplate.html corresponds to llvm.org/docs/SphinxQuickstartTemplate.html. The Sphinx Quickstart Template is useful when creating a new document.
It is possible to cross-compile LLVM itself. That is, you can create LLVM executables and libraries to be hosted on a platform different from the platform where they are built (a Canadian Cross build). To configure a cross-compile, supply the configure script with --build and --host options that are different. The values of these options must be legal target triples that your GCC compiler supports.
The result of such a build is executables that are not runnable on on the build host (–build option) but can be executed on the compile host (–host option).
Check How To Cross-Compile Clang/LLVM using Clang/LLVM and Clang docs on how to cross-compile in general for more information about cross-compiling.
The LLVM build system is capable of sharing a single LLVM source tree among several LLVM builds. Hence, it is possible to build LLVM for several different platforms or configurations using the same source tree.
This is accomplished in the typical autoconf manner:
Change directory to where the LLVM object files should live:
% cd OBJ_ROOT
Run the configure script found in the LLVM source directory:
% $LLVM_SRC_DIR/configure
The LLVM build will place files underneath OBJ_ROOT in directories named after the build type:
Debug Builds with assertions enabled (the default)
Tools
OBJ_ROOT/Debug+Asserts/binLibraries
OBJ_ROOT/Debug+Asserts/lib
Release Builds
Tools
OBJ_ROOT/Release/binLibraries
OBJ_ROOT/Release/lib
Profile Builds
Tools
OBJ_ROOT/Profile/binLibraries
OBJ_ROOT/Profile/lib