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.
- - -Each directory to participate in the build needs to have a file named - Makefile. This is the file first read by make. It has three - sections:
-Every project must have a Makefile.common file at its top source - directory. This file serves three purposes:
-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 make variables that - have been set before Makefile.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) or archive - library (.a) built. Archive libraries are the default. For example:
-- LIBRARYNAME = mylib - SHARED_LIBRARY = 1 - ARCHIVE_LIBRARY = 1 --
says to build a library named "mylib" with both a shared library - (mylib.so) and an archive library (mylib.a) version. 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 desirable 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:
-- LIBRARYNAME := MyMod - LOADABLE_MODULE := 1 - LINK_COMPONENTS := support system --
Use of the LOADABLE_MODULE facility implies several things:
-A loadable module is loaded by LLVM via the facilities of libtool's libltdl - library which is part of lib/System implementation.
-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:
-- cd examples/Fibonacci - make VERBOSE=1 --
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).
- -| Target Name | Implied Targets | Target Description | -
|---|---|---|
| all | - | Compile the software recursively. Default target. - |
| all-local | - | Compile the software in the local directory only. - |
| check | - | Change to the test directory in a project and run the - test suite there. - |
| check-local | - | Run a local test suite. Generally this is only defined in the - Makefile of the project's test directory. - |
| clean | - | Remove built objects recursively. - |
| clean-local | - | Remove built objects from the local directory only. - |
| dist | all | -Prepare a source distribution tarball. - |
| dist-check | all | -Prepare a source distribution tarball and check that it builds. - |
| dist-clean | clean | -Clean source distribution tarball temporary files. - |
| install | all | -Copy built objects to installation directory. - |
| preconditions | all | -Check to make sure configuration and makefiles are up to date. - |
| printvars | all | -Prints variables defined by the makefile system (for debugging). - |
| tags | - | Make C and C++ tags files for emacs and vi. - |
| uninstall | - | Remove built objects from installation 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 is the same as all but it operates only on - the current directory instead of recursively.
-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 does the same thing as clean but only for the current - (local) directory.
-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 is a special form of the clean clean target. It performs a - normal clean but also removes things pertaining to building the - distribution.
-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 just causes the LLVM makefiles to print out some of - the makefile variables so that you can double check how things are set.
-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.
-Use with caution.
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.
-Override variables can be used to override the default - values provided by the LLVM makefile system. These variables can be set in - several ways:
-The override variables are given below:
-Variables listed in the table below can be used by the user's Makefile but - should not be changed. Changing the value will generally cause the build to go - wrong, so don't do it.
-Variables listed below are used by the LLVM Makefile System - and considered internal. You should not use these variables under any - circumstances.
-- Archive - AR.Flags - BaseNameSources - BCCompile.C - BCCompile.CXX - BCLinkLib - C.Flags - Compile.C - CompileCommonOpts - Compile.CXX - ConfigStatusScript - ConfigureScript - CPP.Flags - CPP.Flags - CXX.Flags - DependFiles - DestArchiveLib - DestBitcodeLib - DestModule - DestSharedLib - DestTool - DistAlways - DistCheckDir - DistCheckTop - DistFiles - DistName - DistOther - DistSources - DistSubDirs - DistTarBZ2 - DistTarGZip - DistZip - ExtraLibs - FakeSources - INCFiles - InternalTargets - LD.Flags - LibName.A - LibName.BC - LibName.LA - LibName.O - LibTool.Flags - Link - LinkModule - LLVMLibDir - LLVMLibsOptions - LLVMLibsPaths - LLVMToolDir - LLVMUsedLibs - LocalTargets - Module - ObjectsBC - ObjectsLO - ObjectsO - ObjMakefiles - ParallelTargets - PreConditions - ProjLibsOptions - ProjLibsPaths - ProjUsedLibs - Ranlib - RecursiveTargets - SrcMakefiles - Strip - StripWarnMsg - TableGen - TDFiles - ToolBuildPath - TopLevelTargets - UserTargets -
-
-