diff --git a/llvm/docs/MakefileGuide.html b/llvm/docs/MakefileGuide.html new file mode 100644 index 000000000000..f7cf48faddc7 --- /dev/null +++ b/llvm/docs/MakefileGuide.html @@ -0,0 +1,458 @@ + + +
+ +This document provides usage information about the LLVM makefile + system. While loosely patterned after the BSD makefile system, LLVM has taken + a deparature 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 variations requried by LLVM from any Makefle norm + are too many to strictly use a more limited tool. Consequently, LLVM requires + simply GNU Make 3.79, a widely portably 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, rpms and other + packages, installing and uninstalling, etc.
+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. This allows your project + to get up and running quickly by utilizing the built-in features that are used + to compile LLVM.
+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 doesn't 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 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 + applicabe to a given directory (e.g. "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 | all | +Test the software recursively. + |
check-local | all-local | +Test the software in the local directory only. + |
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 check | +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. + |
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 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.
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+TBD
+Variables are used to tell the LLVM Makefile System what to do and to + obtain information from it. The sections below describe the three kinds of + 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.
+Variable Name | Variable Description |
---|---|
BUILD_ARCHIVE | +If set to any value, causes an archive (.a) library to be built. | +
BUILT_SOURCES | +Specifies a set of source files that are generated. These will be + built before any other target processing to ensure they are present. | +
BUILT_SOURCES | +If set to any value, causes a bytecode library (.bc) to be built. | +
BUILT_SOURCES | +Specivies a set of configuration files to be installed. | +
DIRS | +Specifies a set of directories that should also be made using the + same goal. These directories will be built serially. | +
DONT_BUILD_RELINKED | +If set to any value, causes a relinked library (.o) not to be built. | +
EXPORTED_SYMBOL_FILE | +Specifies the name of a single file that contains a list of the + symbols to be exported by the linker. One symbol per line. | +
LEVEL | +Specify the level of nesting from the top level. (Required) | +
LIBRARYNAME | +Specify the name of the library to be built. (Required For Libraries) | +
LLVMLIBS | +Specify the set of libraries from the LLVM $(OBJDIR) that will be + linked into the tool or library. | +
OPTIONAL_DIRS | +Specify a set of directories that may be built, but if they don't + build, the recursive make doesn't stop. | +
PARALLEL_DIRS | +Specify a set of directories to build recursively and in parallel if + the -j option was used with make. | +
SHARED_LIBRARY | +If set to any value, causes a shared library (.so) to be built. + (Optional) | +
SOURCES | +Specifies the list of source files in the current directory to be + acted upon. Source files of any type may be specified (programs, + documentation, config files, etc.) | +
TARGET | +Specifies the name of the LLVM code generation target that the + current directory builds. | +
TOOLNAME | +Specifies the name of the tool to build. (Required For Tools) | +
USEDLIBS | +Specifies the list of project libraries that will be linked into the + tool or library. | +
Variables listed in the table below can be used to override the default + values provided by the LLVM makefile system. These variables should be set + after the inclusion of $(LEVEL)/Makefile.common.
+Variable Name | Variable Description |
---|---|
C | +The name (and optional path) of the 'C' compiler (gcc normally). | +
CFLAGS | +The set of options to be passed to the 'C' compiler on every + compile. | +
CPP | +The name (and optional path) of the 'C' pre-processor (cpp normally). + | +
CXX | +The name (and optional path) of the C++ compiler (g++ normally). | +
LD | +The name (and optional path) of the system linker (gcc normally). | +
LIBTOOL | +The name (and optional path) of the libtool tool (libtool normally). | +
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.
+Variable Name | Variable Description |
---|---|
BUILD_SRC_DIR | +The project directory contaning the directories source files. | +
BUILD_OBJ_DIR | +The project directory that will receive the object files. | +
DESTDIR | +The top level directory into which files are installed. | +
LLVM_SRC_ROOT | +The top level directory of the LLVM source. | +
LLVM_OBJ_ROOT | +The top level directory of the LLVM objects. | +
OBJDIR | +The directory in which the project's object files should be placed. | +
LIBDIR | +The directory in which the project's library files should be placed. | +
TOOLDIR | +The directory in which the project's executable tools should be + placed. | +