Stand-alone Builds¶

Stand-alone builds allow you to build a sub-project against a pre-builtversion of the clang or llvm libraries that is already present on yoursystem.

You can use the source code from a standard checkout of the llvm-project(as described above) to do stand-alone builds, but you may also buildfrom asparse checkout or from thetarballs available on thereleasespage.

For stand-alone builds, you must have an llvm install that is configuredproperly to be consumable by stand-alone builds of the other projects.This could be a distro provided LLVM install, or you can build it yourself,like this:

cmake -G Ninja -S path/to/llvm-project/llvm -B $builddir \      -DLLVM_INSTALL_UTILS=ON \      -DCMAKE_INSTALL_PREFIX=/path/to/llvm/install/prefix \      < other options >ninja -C $builddir install

Once llvm is installed, to configure a project for a stand-alone build, invoke CMake like this:

cmake -G Ninja -S path/to/llvm-project/$subproj \      -B $buildir_subproj \      -DLLVM_EXTERNAL_LIT=/path/to/lit \      -DLLVM_ROOT=/path/to/llvm/install/prefix

Notice that:

• The stand-alone build needs to happen in a folder that is not theoriginal folder where LLVMN was built($builddir!=$builddir_subproj).

• LLVM_ROOT should point to the prefix of your llvm installation,so for example, if llvm is installed into/usr/bin and/usr/lib64, then you should pass-DLLVM_ROOT=/usr/.

• Both theLLVM_ROOT andLLVM_EXTERNAL_LIT options arerequired to do stand-alone builds for all sub-projects. Additionalrequired options for each sub-project can be found in the tablebelow.

Thecheck-$subproj andinstall build targets are supported for thesub-projects listed in the table below.

Example for building stand-aloneclang:

#!/bin/shbuild_llvm=`pwd`/build-llvmbuild_clang=`pwd`/build-clanginstallprefix=`pwd`/installllvm=`pwd`/llvm-projectmkdir -p $build_llvmmkdir -p $installprefixcmake -G Ninja -S $llvm/llvm -B $build_llvm \      -DLLVM_INSTALL_UTILS=ON \      -DCMAKE_INSTALL_PREFIX=$installprefix \      -DCMAKE_BUILD_TYPE=Releaseninja -C $build_llvm installcmake -G Ninja -S $llvm/clang -B $build_clang \      -DLLVM_EXTERNAL_LIT=$build_llvm/utils/lit \      -DLLVM_ROOT=$installprefixninja -C $build_clang

Hardware¶

LLVM is known to work on the following host platforms:

Note that Debug builds require a lot of time and disk space. An LLVM-only buildwill need about 1-3 GB of space. A full build of LLVM and Clang will need around15-20 GB of disk space. The exact space requirements will vary by system. (Itis so large because of all the debugging information and the fact that thelibraries are statically linked into multiple tools).

If you are space-constrained, you can build only selected tools or onlyselected targets. The Release build requires considerably less space.

The LLVM suitemay compile on other platforms, but it is not guaranteed to doso. If compilation is successful, the LLVM utilities should be able toassemble, disassemble, analyze, and optimize LLVM bitcode. Code generationshould work as well, although the generated native code may not work on yourplatform.

Software¶

Compiling LLVM requires that you have several software packages installed. Thetable below lists those required packages. The Package column is the usual namefor the software package that LLVM depends on. The Version column provides“known to work” versions of the package. The Notes column describes how LLVMuses the package and provides other details.

Additionally, your compilation host is expected to have the usual plethora ofUnix utilities. Specifically:

• ar — archive library builder

• bzip2 — bzip2 command for distribution generation

• bunzip2 — bunzip2 command for distribution checking

• chmod — change permissions on a file

• cat — output concatenation utility

• cp — copy files

• date — print the current date/time

• echo — print to standard output

• egrep — extended regular expression search utility

• find — find files/dirs in a file system

• grep — regular expression search utility

• gzip — gzip command for distribution generation

• gunzip — gunzip command for distribution checking

• install — install directories/files

• mkdir — create a directory

• mv — move (rename) files

• ranlib — symbol table builder for archive libraries

• rm — remove (delete) files and directories

• sed — stream editor for transforming output

• sh — Bourne shell for make build scripts

• tar — tape archive for distribution generation

• test — test things in file system

• unzip — unzip command for distribution checking

• zip — zip command for distribution generation

Host C++ Toolchain, both Compiler and Standard Library¶

LLVM is very demanding of the host C++ compiler, and as such tends to exposebugs in the compiler. We also attempt to follow improvements and developments inthe C++ language and library reasonably closely. As such, we require a modernhost C++ toolchain, both compiler and standard library, in order to build LLVM.

LLVM is written using the subset of C++ documented incodingstandards. To enforce this language version, we check the mostpopular host toolchains for specific minimum versions in our build systems:

• Clang 5.0

• Apple Clang 10.0

• GCC 7.4

• Visual Studio 2019 16.8

Anything older than these toolchainsmay work, but will require forcing thebuild system with a special option and is not really a supported host platform.Also note that older versions of these compilers have often crashed ormiscompiled LLVM.

For less widely used host toolchains such as ICC or xlC, be aware that a veryrecent version may be required to support all of the C++ features used in LLVM.

We track certain versions of software that areknown to fail when used aspart of the host toolchain. These even include linkers at times.

GNU ld 2.16.X. Some 2.16.X versions of the ld linker will produce very longwarning messages complaining that some “.gnu.linkonce.t.*” symbol wasdefined in a discarded section. You can safely ignore these messages as they areerroneous and the linkage is correct. These messages disappear using ld 2.17.

GNU binutils 2.17: Binutils 2.17 containsa bug which causes huge linktimes (minutes instead of seconds) when building LLVM. We recommend upgradingto a newer version (2.17.50.0.4 or later).

GNU Binutils 2.19.1 Gold: This version of Gold containeda bug which causesintermittent failures when building LLVM with position independent code. Thesymptom is an error about cyclic dependencies. We recommend upgrading to anewer version of Gold.

%gcc_version=7.4.0%wgethttps://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2%wgethttps://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig%wgethttps://ftp.gnu.org/gnu/gnu-keyring.gpg%signature_invalid=`gpg--verify--no-default-keyring--keyring./gnu-keyring.gpggcc-${gcc_version}.tar.bz2.sig`%if[$signature_invalid];thenecho"Invalid signature";exit1;fi%tar-xvjfgcc-${gcc_version}.tar.bz2%cdgcc-${gcc_version}%./contrib/download_prerequisites%cd..%mkdirgcc-${gcc_version}-build%cdgcc-${gcc_version}-build%$PWD/../gcc-${gcc_version}/configure--prefix=$HOME/toolchains--enable-languages=c,c++%make-j$(nproc)%makeinstall

%mkdirbuild%cdbuild%CC=$HOME/toolchains/bin/gccCXX=$HOME/toolchains/bin/g++\cmake..-DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"

Terminology and Notation¶

Throughout this manual, the following names are used to denote paths specific tothe local system and working environment.These are not environment variablesyou need to set but just strings used in the rest of this document below. Inany of the examples below, simply replace each of these names with theappropriate pathname on your local system. All these paths are absolute:

SRC_ROOT

This is the top level directory of the LLVM source tree.

OBJ_ROOT

This is the top level directory of the LLVM object tree (i.e. the tree whereobject files and compiled programs will be placed. It can be the same asSRC_ROOT).

Local LLVM Configuration¶

Once checked out repository, the LLVM suite source code must be configuredbefore being built. This process uses CMake. Unlike the normalconfigurescript, CMake generates the build files in whatever format you request as wellas various*.inc files, andllvm/include/llvm/Config/config.h.cmake.

Variables are passed tocmake on the command line using the format-D<variablename>=<value>. The following variables are some common optionsused by people developing LLVM.

• CMAKE_C_COMPILER

• CMAKE_CXX_COMPILER

• CMAKE_BUILD_TYPE

• CMAKE_INSTALL_PREFIX

• Python3_EXECUTABLE

• LLVM_TARGETS_TO_BUILD

• LLVM_ENABLE_PROJECTS

• LLVM_ENABLE_RUNTIMES

• LLVM_ENABLE_DOXYGEN

• LLVM_ENABLE_SPHINX

• LLVM_BUILD_LLVM_DYLIB

• LLVM_LINK_LLVM_DYLIB

• LLVM_PARALLEL_LINK_JOBS

• LLVM_OPTIMIZED_TABLEGEN

Seethe list of frequently-used CMake variablesfor more information.

To configure LLVM, follow these steps:

1. Change directory into the object root directory:

   %cdOBJ_ROOT

2. Run thecmake:

   %cmake-G"Unix Makefiles"-DCMAKE_BUILD_TYPE=<type>-DCMAKE_INSTALL_PREFIX=/install/path  [other options] SRC_ROOT

Compiling the LLVM Suite Source Code¶

Unlike with autotools, with CMake your build type is defined at configuration.If you want to change your build type, you can re-run cmake with the followinginvocation:

%cmake-G"Unix Makefiles"-DCMAKE_BUILD_TYPE=<type>SRC_ROOT

Between runs, CMake preserves the values set for all options. CMake has thefollowing build types defined:

Debug

These builds are the default. The build system will compile the tools andlibraries unoptimized, with debugging information, and asserts enabled.

Release

For these builds, the build system will compile the tools and librarieswith optimizations enabled and not generate debug info. CMakes defaultoptimization level is -O3. This can be configured by setting theCMAKE_CXX_FLAGS_RELEASE variable on the CMake command line.

RelWithDebInfo

These builds are useful when debugging. They generate optimized binaries withdebug information. CMakes default optimization level is -O2. This can beconfigured by setting theCMAKE_CXX_FLAGS_RELWITHDEBINFO variable on theCMake command line.

Once you have LLVM configured, you can build it by entering theOBJ_ROOTdirectory and issuing the following command:

%make

If the build fails, pleasecheck here to see if you are using a version ofGCC that is known not to compile LLVM.

If you have multiple processors in your machine, you may wish to use some of theparallel build options provided by GNU Make. For example, you could use thecommand:

%make-j2

There are several special targets which are useful when working with the LLVMsource code:

makeclean

Removes all files generated by the build. This includes object files,generated C/C++ files, libraries, and executables.

makeinstall

Installs LLVM header files, libraries, tools, and documentation in a hierarchyunder$PREFIX, specified withCMAKE_INSTALL_PREFIX, whichdefaults to/usr/local.

makedocs-llvm-html

If configured with-DLLVM_ENABLE_SPHINX=On, this will generate a directoryatOBJ_ROOT/docs/html which contains the HTML formatted documentation.

Cross-Compiling LLVM¶

It is possible to cross-compile LLVM itself. That is, you can create LLVMexecutables and libraries to be hosted on a platform different from the platformwhere they are built (a Canadian Cross build). To generate build files forcross-compiling CMake provides a variableCMAKE_TOOLCHAIN_FILE which candefine compiler flags and variables used during the CMake test operations.

The result of such a build is executables that are not runnable on the buildhost but can be executed on the target. As an example the following CMakeinvocation can generate build files targeting iOS. This will work on macOSwith the latest Xcode:

%cmake-G"Ninja"-DCMAKE_OSX_ARCHITECTURES="armv7;armv7s;arm64"  -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake  -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off  -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]  <PATH_TO_LLVM>

Note: There are some additional flags that need to be passed when building foriOS due to limitations in the iOS SDK.

CheckHow to cross-compile Clang/LLVM using Clang/LLVM andClang docs on how to cross-compile in general for more informationabout cross-compiling.

The Location of LLVM Object Files¶

The LLVM build system is capable of sharing a single LLVM source tree amongseveral LLVM builds. Hence, it is possible to build LLVM for several differentplatforms or configurations using the same source tree.

• Change directory to where the LLVM object files should live:

  %cdOBJ_ROOT

• Runcmake:

  %cmake-G"Unix Makefiles"-DCMAKE_BUILD_TYPE=ReleaseSRC_ROOT

The LLVM build will create a structure underneathOBJ_ROOT that matches theLLVM source tree. At each level where source files are present in the sourcetree there will be a correspondingCMakeFiles directory in theOBJ_ROOT.Underneath that directory there is another directory with a name ending in.dir under which you’ll find object files for each source.

For example:

%cdllvm_build_dir%findlib/Support/-nameAPFloat*lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o

Optional Configuration Items¶

If you’re running on a Linux system that supports thebinfmt_miscmodule, and you have root access on the system, you can set your system up toexecute LLVM bitcode files directly. To do this, use commands like this (thefirst command may not be required if you are already using the module):

%mount-tbinfmt_miscnone/proc/sys/fs/binfmt_misc%echo':llvm:M::BC::/path/to/lli:'>/proc/sys/fs/binfmt_misc/register%chmodu+xhello.bc(ifneeded)%./hello.bc

This allows you to execute LLVM bitcode files directly. On Debian, you can alsouse this command instead of the ‘echo’ command above:

%sudoupdate-binfmts--installllvm/path/to/lli--magic'BC'

llvm/cmake¶

Generates system build files.

llvm/cmake/modules

Build configuration for llvm user defined options. Checks compiler version andlinker flags.

llvm/cmake/platforms

Toolchain configuration for Android NDK, iOS systems and non-Windows hosts totarget MSVC.

llvm/examples¶

• Some simple examples showing how to use LLVM as a compiler for a customlanguage - including lowering, optimization, and code generation.

• Kaleidoscope Tutorial: Kaleidoscope language tutorial run through theimplementation of a nice little compiler for a non-trivial languageincluding a hand-written lexer, parser, AST, as well as code generationsupport using LLVM- both static (ahead of time) and various approaches toJust In Time (JIT) compilation.Kaleidoscope Tutorial for complete beginner.

• BuildingAJIT: Examples of theBuildingAJIT tutorial that shows how LLVM’sORC JIT APIs interact with other parts of LLVM. It also, teaches how torecombine them to build a custom JIT that is suited to your use-case.

llvm/include¶

Public header files exported from the LLVM library. The three main subdirectories:

llvm/include/llvm

All LLVM-specific header files, and subdirectories for different portions ofLLVM:Analysis,CodeGen,Target,Transforms, etc…

llvm/include/llvm/Support

Generic support libraries provided with LLVM but not necessarily specific toLLVM. For example, some C++ STL utilities and a Command Line option processinglibrary store header files here.

llvm/include/llvm/Config

Header files configured bycmake. They wrap “standard” UNIX andC header files. Source code can include these header files whichautomatically take care of the conditional #includes thatcmakegenerates.

llvm/lib¶

Most source files are here. By putting code in libraries, LLVM makes it easy toshare code among thetools.

llvm/lib/IR/

Core LLVM source files that implement core classes like Instruction andBasicBlock.

llvm/lib/AsmParser/

Source code for the LLVM assembly language parser library.

llvm/lib/Bitcode/

Code for reading and writing bitcode.

llvm/lib/Analysis/

A variety of program analyses, such as Call Graphs, Induction Variables,Natural Loop Identification, etc.

llvm/lib/Transforms/

IR-to-IR program transformations, such as Aggressive Dead Code Elimination,Sparse Conditional Constant Propagation, Inlining, Loop Invariant Code Motion,Dead Global Elimination, and many others.

llvm/lib/Target/

Files describing target architectures for code generation. For example,llvm/lib/Target/X86 holds the X86 machine description.

llvm/lib/CodeGen/

The major parts of the code generator: Instruction Selector, InstructionScheduling, and Register Allocation.

llvm/lib/MC/

The libraries represent and process code at machine code level. Handlesassembly and object-file emission.

llvm/lib/ExecutionEngine/

Libraries for directly executing bitcode at runtime in interpreted andJIT-compiled scenarios.

llvm/lib/Support/

Source code that corresponding to the header files inllvm/include/ADT/andllvm/include/Support/.

llvm/bindings¶

Contains bindings for the LLVM compiler infrastructure to allowprograms written in languages other than C or C++ to take advantage of the LLVMinfrastructure.LLVM project provides language bindings for OCaml and Python.

llvm/projects¶

Projects not strictly part of LLVM but shipped with LLVM. This is also thedirectory for creating your own LLVM-based projects which leverage the LLVMbuild system.

llvm/test¶

Feature and regression tests and other sanity checks on LLVM infrastructure. Theseare intended to run quickly and cover a lot of territory without being exhaustive.

test-suite¶

A comprehensive correctness, performance, and benchmarking test suitefor LLVM. This comes in aseparategitrepository<https://github.com/llvm/llvm-test-suite>, because it contains alarge amount of third-party code under a variety of licenses. Fordetails see theTesting Guide document.

llvm/tools¶

Executables built out of the librariesabove, which form the main part of the user interface. You can always get helpfor a tool by typingtool_name-help. The following is a brief introductionto the most important tools. More detailed information is intheCommand Guide.

bugpoint

bugpoint is used to debug optimization passes or code generation backendsby narrowing down the given test case to the minimum number of passes and/orinstructions that still cause a problem, whether it is a crash ormiscompilation. SeeHowToSubmitABug.html for more information on usingbugpoint.

llvm-ar

The archiver produces an archive containing the given LLVM bitcode files,optionally with an index for faster lookup.

llvm-as

The assembler transforms the human readable LLVM assembly to LLVM bitcode.

llvm-dis

The disassembler transforms the LLVM bitcode to human readable LLVM assembly.

llvm-link

llvm-link, not surprisingly, links multiple LLVM modules into a singleprogram.

lli

lli is the LLVM interpreter, which can directly execute LLVM bitcode(although very slowly…). For architectures that support it (currently x86,Sparc, and PowerPC), by default,lli will function as a Just-In-Timecompiler (if the functionality was compiled in), and will execute the codemuch faster than the interpreter.

llc

llc is the LLVM backend compiler, which translates LLVM bitcode to anative code assembly file.

opt

opt reads LLVM bitcode, applies a series of LLVM to LLVM transformations(which are specified on the command line), and outputs the resultantbitcode. ‘opt-help’ is a good way to get a list of theprogram transformations available in LLVM.

opt can also run a specific analysis on an input LLVM bitcodefile and print the results. Primarily useful for debugginganalyses, or familiarizing yourself with what an analysis does.

llvm/utils¶

Utilities for working with LLVM source code; some are part of the build processbecause they are code generators for parts of the infrastructure.

codegen-diff

codegen-diff finds differences between code that LLCgenerates and code that LLI generates. This is useful if you aredebugging one of them, assuming that the other generates correct output. Forthe full user manual, run`perldoccodegen-diff'.

emacs/

Emacs and XEmacs syntax highlighting for LLVM assembly files and TableGendescription files. See theREADME for information on using them.

getsrcs.sh

Finds and outputs all non-generated source files,useful if one wishes to do a lot of development across directoriesand does not want to find each file. One way to use it is to run,for example:xemacs`utils/getsources.sh` from the top of the LLVM sourcetree.

llvmgrep

Performs anegrep-H-n on each source file in LLVM andpasses to it a regular expression provided onllvmgrep’s commandline. This is an efficient way of searching the source base for aparticular regular expression.

TableGen/

Contains the tool used to generate registerdescriptions, instruction set descriptions, and even assemblers from commonTableGen description files.

vim/

vim syntax-highlighting for LLVM assembly filesand TableGen description files. See theREADME for how to use them.

Example with clang¶

1. First, create a simple C file, name it ‘hello.c’:

   #include<stdio.h>intmain(){printf("hello world\n");return0;}

2. Next, compile the C file into a native executable:

   %clanghello.c-ohello

   Note

   Clang works just like GCC by default. The standard -S and -c argumentswork as usual (producing a native .s or .o file, respectively).

3. Next, compile the C file into an LLVM bitcode file:

   %clang-O3-emit-llvmhello.c-c-ohello.bc

   The -emit-llvm option can be used with the -S or -c options to emit an LLVM.ll or.bc file (respectively) for the code. This allows you to usethestandard LLVM tools on the bitcode file.

4. Run the program in both forms. To run the program, use:

   %./hello

   and

   %llihello.bc

   The second examples shows how to invoke the LLVM JIT,lli.

5. Use thellvm-dis utility to take a look at the LLVM assembly code:

   %llvm-dis<hello.bc|less

6. Compile the program to native assembly using the LLC code generator:

   %llchello.bc-ohello.s

7. Assemble the native assembly language file into a program:

   %/opt/SUNWspro/bin/cc-xarch=v9hello.s-ohello.native# On Solaris%gcchello.s-ohello.native# On others

8. Execute the native code program:

   %./hello.native

   Note that using clang to compile directly to native code (i.e. when the-emit-llvm option is not present) does steps 6/7/8 for you.