Using the autotools-generated configure script
A standard way to build LLVM is to generate the platform-specific Makefiles by means of the configure
script that was created with the GNU autotools. This build system is quite popular, and you are probably familiar with it. It supports several different configuration options.
Note
You need to install GNU autotools on your machine only if you intend to change the LLVM build system, in which case, you will generate a new configure
script. Usually, it is unnecessary to do so.
Take out some time to look at the possible options using the following commands:
A few of them deserve a brief explanation:
--enable-optimized
: This option allows us to compile LLVM/Clang without debug support and with optimizations. By default, this option is turned off. Debug support, as well as the disabling of optimizations, is recommended if you are using LLVM libraries for development, but it should be discarded for deployment since the lack of optimizations introduces a significant slowdown in LLVM.
--enable-assertions
: This option enables assertions in the code. This option is very useful when developing LLVM core libraries. It is turned on by default.
--enable-shared
: This option allows us to build LLVM/Clang libraries as shared libraries and link the LLVM tools against them. If you plan to develop a tool outside the LLVM build system and wish to dynamically link against the LLVM libraries, you should turn it on. This option is turned off by default.
--enable-jit
: This option enables Just-In-Time Compilation for all the targets that support it. It is turned on by default.
--prefix
: This is the path to the installation directory where the final LLVM/Clang tools and libraries will be installed; for example, --prefix=/usr/local/llvm
will install binaries under /usr/local/llvm/bin
and libraries under /usr/local/llvm/lib
.
--enable-targets
: This option allows us to select the set of targets that the compiler must be able to emit code for. It is worth mentioning that LLVM is able to perform cross-compilation, that is, compile programs that will run on other platforms, such as ARM, MIPS, and so on. This option defines which backends to include in the code generation libraries. By default, all the targets are compiled, but you can save compilation time by specifying only the ones you are interested in.
Note
This option is not enough to generate a standalone cross-compiler. Refer to Chapter 8, Cross-platform Compilation, for the necessary steps to generate one.
After you run configure
with the desired parameters, you need to complete the build with the classic make
and make install
duo. We will give you an example next.
Building and configuring with Unix
In this example, we will build an unoptimized (debug) LLVM/Clang with a sequence of commands that suit any Unix-based system or Cygwin. Instead of installing at /usr/local/llvm
, as in the previous examples, we will build and install it in our home directory, explaining how to install LLVM without root privileges. This is customary when working as a developer. In this way, you can also maintain the multiple versions that have been installed. If you want, you can change the installation folder to /usr/local/llvm
, making a system-wide installation. Just remember to use sudo
when creating the installation directory and to run make install
. The sequence of commands to be used is as follows:
In this section, we will create a separate directory to hold the object files, that is, the intermediary build byproducts. Do not build in the same folder that is used to keep the source files. Use the following commands with options explained in the previous section:
Note
You can optionally use make -jN
to allow up to N
compiler instances to work in parallel and speed up the build process. For example, you can experiment with make -j4
(or a slightly larger number) if your processor has four cores.
Allow some time for the compilation and installation of all components to finish. Note that the build scripts will also handle the other repositories that you downloaded and put in the LLVM source tree. There is no need to configure Clang or Clang extra tools separately.
To check whether the build succeeded, it is always useful to use the echo $?
shell command. The $?
shell variable returns the exit code of the last process that you ran in your shell session, while echo
prints it to the screen. Thus, it is important to run this command immediately after your make
commands. If the build succeeded, the make
command will always return 0
, as with any other program that has completed its execution successfully:
Configure your shell's PATH environment variable to be able to easily access the recently installed binaries, and make your first test by asking for the Clang version:
LLVM offers an alternative cross-platform build system based on CMake, instead of the traditional configuration scripts. CMake can generate specialized Makefiles for your platform in the same way as the configuration scripts do, but CMake is more flexible and can also generate build files for other systems, such as Ninja, Xcode, and Visual Studio.
Ninja, on the other hand, is a small and fast build system that substitutes GNU Make and its associated Makefiles. If you are curious to read the motivation and the story behind Ninja, visit http://aosabook.org/en/posa/ninja.html. CMake can be configured to generate Ninja build files instead of Makefiles, giving you the option to use either CMake and GNU Make or CMake and Ninja.
Nevertheless, by using the latter, you can enjoy very quick turnaround times when making changes to the LLVM source code and recompiling it. This scenario is especially useful if you intend to develop a tool or a plugin inside the LLVM source tree and depend on the LLVM build system to compile your project.
Make sure that you have CMake and Ninja installed. For example, in Ubuntu systems, use the following command:
LLVM with CMake also offers a number of build-customizing options. A full list of options is available at http://llvm.org/docs/CMake.html. The following is a list of options that correspond to the same set that we presented earlier for autotools-based systems. The default values for these flags are the same as those for the corresponding configure
script flags:
CMAKE_BUILD_TYPE
: This is a string value that specifies whether the build will be Release
or Debug
. A Release
build is equivalent to use the --enable-optimized
flag in the configure
script, while a Debug
build is equivalent to the --disable-optimized
flag.
CMAKE_ENABLE_ASSERTIONS
: This is a Boolean value that maps to the --enable-assertions
configure flag.
BUILD_SHARED_LIBS
: This is a Boolean value that maps to the -enable-shared
configure flag, establishing whether the libraries should be shared or static. Shared libraries are not supported on Windows platforms.
CMAKE_INSTALL_PREFIX
: This is a string value that maps to the --prefix
configure flag, providing the installation path.
LLVM_TARGETS_TO_BUILD
: This is a semicolon-separated list of targets to build, roughly mapping to the comma-separated list of targets used in the --enable-targets
configure flag.
To set any of these parameter-value pairs, supply the -DPARAMETER=value
argument flag to the cmake
command.
Building with Unix using CMake and Ninja
We will reproduce the same example that we presented earlier for the configure
scripts, but this time, we will use CMake and Ninja to build it:
First, create a directory to contain the build and installation files:
Remember that you need to use a different folder than the one used to hold the LLVM source files. Next, it is time to launch CMake with the set of options that you chose:
You should substitute /PATHTOSOURCE
with the absolute location of your LLVM source folder. You can optionally omit the -G Ninja
argument if you want to use traditional GNU Makefiles. Now, finish the build with either ninja
or make
, depending on which you chose. For ninja
, use the following command:
For make
, use the following command:
As we did earlier in the previous example, we can issue a simple command to check whether the build succeeded. Remember to use it immediately after the last build command, without running other commands in between, because it returns the exit value of the last program that you ran in the current shell session:
If the preceding command returns zero, we are good to go. Finally, configure your PATH environment variable and use your new compiler:
If the build commands return a nonzero value, it means that an error has occurred. In this case, either Make or Ninja will print the error to make it visible for you. Make sure to focus on the first error that appeared to find help. LLVM build errors in a stable release typically happen when your system does not meet the criteria for the required software versions. The most common issues come from using an outdated compiler. For example, building LLVM 3.4 with GNU g++ Version 4.4.3 will result in the following compilation error, after successfully compiling more than half of the LLVM source files:
To solve this, you could hack the LLVM source code to work around this issue (and you will find how to do this if you either search online or look at the source yourself), but you will not want to patch every LLVM version that you want to compile. Updating your compiler is far simpler and is certainly the most appropriate solution.
In general, when running into build errors in a stable build, concentrate on what differences your system has in comparison with the recommended setup. Remember that the stable builds have been tested on several platforms. On the other hand, if you are trying to build an unstable SVN release, it is possible that a recent commit broke the build for your system, and it is easier to backtrack to an SVN release that works.