Building from sources

In the absence of prebuilt binaries, LLVM and Clang can be built from scratch by obtaining the source code first. Building the project from the source is a good way to start understanding more about the LLVM structure. Additionally, you will be able to fine-tune the configuration parameters to obtain a customized compiler.

System requirements

An updated list of the LLVM-supported platforms can be found at http://llvm.org/docs/GettingStarted.html#hardware. Also, a comprehensive and updated set of software prerequisites to compile LLVM is described at http://llvm.org/docs/GettingStarted.html#software. In Ubuntu systems, for example, the software dependencies can be resolved with the following command:

$ sudo apt-get install build-essential zlib1g-dev python

If you are using an old version of a Linux distribution with outdated packages, make an effort to update your system. LLVM sources are very demanding on the C++ compiler that is used to build them, and relying on an old C++ compiler is likely to result in a failed build attempt.

Obtaining sources

The LLVM source code is distributed under a BSD-style license and can be downloaded from the official website or through SVN repositories. To download the sources from the 3.4 release, you can either go to the website, http://llvm.org/releases/download.html#3.4, or directly download and prepare the sources for compilation as follows. Note that you will always need Clang and LLVM, but the clang-tools-extra bundle is optional. However, if you intend to exercise the tutorial in Chapter 10, Clang Tools with LibTooling, you will need it. Refer to the next chapter for information on building additional projects. Use the following commands to download and install LLVM, Clang, and Clang extra tools:

$ wget http://llvm.org/releases/3.4/llvm-3.4.src.tar.gz
$ wget http://llvm.org/releases/3.4/clang-3.4.src.tar.gz
$ wget http://llvm.org/releases/3.4/clang-tools-extra-3.4.src.tar.gz
$ tar xzf llvm-3.4.src.tar.gz; tar xzf clang-3.4.src.tar.gz
$ tar xzf clang-tools-extra-3.4.src.tar.gz
$ mv llvm-3.4 llvm
$ mv clang-3.4 llvm/tools/clang
$ mv clang-tools-extra-3.4 llvm/tools/clang/tools/extra

Note

Downloaded sources in Windows can be unpacked using gunzip, WinZip, or any other available decompressing tool.

SVN

To obtain the sources directly from the SVN repositories, make sure you have the subversion package available on your system. The next step is to decide whether you want the latest version stored in the repository or whether you want a stable version. In the case of the latest version (in trunk), you can use the following sequence of commands, assuming that you are already in the folder where you want to put the sources:

$ svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
$ cd llvm/tools
$ svn co http://llvm.org/svn/llvm-project/cfe/trunk clang
$ cd ../projects
$ svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt
$ cd ../tools/clang/tools
$ svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra

If you want to use a stable version (for example, version 3.4), substitute trunk for tags/RELEASE_34/final in all the commands. You may also be interested in an easy way to navigate the LLVM SVN repository to see the commit history, logs, and source tree structure. For this, you can go to http://llvm.org/viewvc.

Git

You can also obtain sources from the Git mirror repositories that sync with the SVN ones:

$ git clone http://llvm.org/git/llvm.git
$ cd llvm/tools
$ git clone http://llvm.org/git/clang.git
$ cd ../projects
$ git clone http://llvm.org/git/compiler-rt.git
$ cd ../tools/clang/tools
$ git clone http://llvm.org/git/clang-tools-extra.git

Building and installing LLVM

The various approaches to build and install LLVM are explained here.

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:

$ cd llvm
$ ./configure --help

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.

  Tip

  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:

$ mkdir where-you-want-to-install
$ mkdir where-you-want-to-build
$ cd where-you-want-to-build

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:

$ / PATH_TO_SOURCE/configure --disable-optimized --prefix=../where-you-want-to-install
$ make && make install

Tip

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:

$ echo $?
0

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:

$ export PATH="$PATH:where-you-want-to-install/bin"
$ clang –v
clang version 3.4

Using CMake and Ninja

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:

$ sudo apt-get install cmake ninja-build

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:

$ mkdir where-you-want-to-build
$ mkdir where-you-want-to-install
$ cd where-you-want-to-build

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:

$ cmake /PATHTOSOURCE -G Ninja -DCMAKE_BUILD_TYPE="Debug" -DCMAKE_INSTALL_PREFIX="../where-you-want-to-install"

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:

$ ninja && ninja install

For make, use the following command:

$ make && make install

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:

$ echo $?
0

If the preceding command returns zero, we are good to go. Finally, configure your PATH environment variable and use your new compiler:

$ export PATH=$PATH:where-you-want-to-install/bin
$ clang -v

Solving build errors

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:

[1385/2218] Building CXX object projects/compiler-rt/lib/interception/CMakeFiles/RTInterception.i386.dir/interception_type_test.cc.o
FAILED: /usr/bin/c++ (...)_test.cc.o -c /local/llvm-3.3/llvm/projects/compiler-rt/lib/interception/interception_type_test.cc
test.cc:28: error: reference to 'OFF64_T' is ambiguous
interception.h:31: error: candidates are: typedef __sanitizer::OFF64_T OFF64_T
sanitizer_internal_defs.h:80: error:                 typedef __sanitizer::u64 __sanitizer::OFF64_T

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.

Using other Unix approaches

Some Unix systems provide package managers that automatically build and install applications from the source. They offer a source-compilation counterpart that was previously tested for your system and also try to solve package-dependency issues. We will now evaluate such platforms in the context of building and installing LLVM and Clang:

• For Mac OS X using MacPorts, we can use the following command:

  $ port install llvm-3.4 clang-3.4
  

• For Mac OS X using Homebrew, we can use the following:

  $ brew install llvm -with-clang
  

• For FreeBSD 9.1 using ports, we can use the following (note that starting from FreeBSD 10, Clang is the default compiler, and thus it is already installed):

  $ cd /usr/ports/devel/llvm34
  $ make install
  $ cd /usr/ports/lang/clang34
  $ make install
  

• For Gentoo Linux, we can use the following:

  $ emerge sys-devel/llvm-3.4 sys-devel/clang-3.4
  

Windows and Microsoft Visual Studio

To compile LLVM and Clang on Microsoft Windows, we use Microsoft Visual Studio 2012 and Windows 8. Perform the following steps:

1. Obtain a copy of Microsoft Visual Studio 2012.
2. Download and install the official binary distribution of the CMake tool available at http://www.cmake.org. During installation, make sure to check the Add CMake to the system PATH for all users option.
3. CMake will generate the project files needed by Visual Studio to configure and build LLVM. First, run the cmake-gui graphic tool. Then, click on the Browse Source… button and select the LLVM source code directory. Next, click on the Browse Build button and choose a directory to put the CMake-generated files, which will be used later by Visual Studio, as shown in the following screenshot:
   
4. Click on Add Entry and define CMAKE_INSTALL_PREFIX to contain the installation path for the LLVM tools, as shown in the following screenshot:
   
5. Additionally, the set of supported targets can be defined using LLVM_TARGETS_TO_BUILD, as shown in the following screenshot. You can optionally add any other entry that defines the CMake parameters we previously discussed.
   
6. Click on the Configure button. A pop-up window asks for the generator of this project and for the compiler to be used; select Use default native compilers and for Visual Studio 2012, select the Visual Studio 11 option. Click on Finish, as shown in the following screenshot:
   

   Tip

   For Visual Studio 2013, use the generator for Visual Studio 12. The name of the generator uses the Visual Studio version instead of its commercial name.

7. After the configuration ends, click on the Generate button. The Visual Studio solution file, LLVM.sln, is then written in the specified build directory. Go to this directory and double-click on this file; it will open the LLVM solution in Visual Studio.
8. To automatically build and install LLVM/Clang, in the tree view window on the left, go to CMakePredefinedTargets, right-click on INSTALL, and select the Build option. The predefined INSTALL target instructs the system to build and install all the LLVM/Clang tools and libraries, as shown in the following screenshot:
   
9. To selectively build and install specific tools or libraries, select the corresponding item in the tree list view window on the left-hand side, right-click on the item, and select the Build option.
10. Add the LLVM binaries install directory to the system's PATH environment variable.

In our example, the install directory is C:\Program Files (x86)\LLVM\install\bin. To directly test the installation without updating the PATH environment variable, issue the following command in a command prompt window:

C:>"C:\Program Files (x86)\LLVM\install\bin\clang.exe" –v
clang version 3.4…

Mac OS X and Xcode

Although LLVM can be compiled for Mac OS X by using regular Unix instructions described earlier, Xcode can also be used:

1. Obtain a copy of Xcode.
2. Download and install the official binary distribution of the CMake tool available at http://www.cmake.org. Make sure to check the Add CMake to the system PATH for all users option.
   
3. CMake is able to generate the project files used by Xcode. First, run the cmake-gui graphic tool. Then, as shown in the preceding screenshot, click on the Browse Source button and select the LLVM source code directory. Next, click on the Browse Build button and choose a directory to add the CMake-generated files, which will be used by Xcode.
4. Click on Add Entry and define CMAKE_INSTALL_PREFIX to contain the installation path for the LLVM tools.
   
5. Additionally, the set of supported targets can be defined using LLVM_TARGETS_TO_BUILD. You can optionally add any other entries that define the CMake parameters we previously discussed.
   
6. Xcode does not support the generation of LLVM Position Independent Code (PIC) libraries. Click on Add Entry and add the LLVM_ENABLE_PIC variable, which was the BOOL type, leaving the checkbox unmarked, as shown in the following screenshot:
   
7. Click on the Configure button. A pop-up window asks for the generator for this project and the compiler to be used. Select Use default native compilers and Xcode. Click on the Finish button to conclude the process, as shown in the following screenshot:
   
8. After the configuration ends, click on the Generate button. The LLVM.xcodeproj file is then written in the build directory that was specified earlier. Go to this directory and double-click on this file to open the LLVM project in Xcode.
9. To build and install LLVM/Clang, select the install scheme.
   
10. Next, click on the Product menu and then select the Build option, as shown in the following screenshot:
    
11. Add the LLVM binaries install directory to the system's PATH environment variable.

In our example, the folder with the installed binaries is /Users/Bruno/llvm/install/bin. To test the installation, use the clang tool from the install directory as follows:

$ /Users/Bruno/llvm/install/bin/clang –v
clang version 3.4…