diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index 4d7e1c4a2cd..af06d757120 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -14,13 +14,23 @@
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 differences between the LLVM way of doing things and - the Makefile norm are too great to 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.
+ 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 @@ -80,9 +89,11 @@
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 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.
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 @@ -108,13 +138,14 @@ first.
Every project must have a Makefile.common file at its top source directory. This file serves three purposes:
@@ -125,14 +156,15 @@Every project must have a Makefile.config at the top of its build directory. This file is generated by the @@ -145,7 +177,7 @@
This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart of the LLVM Makefile System. It provides all the logic, dependencies, and @@ -164,6 +196,75 @@ 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), archive library + (.a) or to not have the default (relinked) library built. For example:
++ LIBRARYNAME = mylib + SHARED_LIBRARY = 1 + ARCHIVE_LIBRARY = 1 + DONT_BUILT_RELINKED = 1 ++
says to build a library named "mylib" with both a shared library + (mylib.so) and an archive library (mylib.a) version but + not to build the relinked object (mylib.o). 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.
+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 + LLVMLIBS = LLVMSupport.a LLVMSystem.a ++
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. +
+Overridable variables can be used to override the default +
Override variables can be used to override the default values provided by the LLVM makefile system. These variables can be set in several ways: