diff options
| author | Bill Wendling <isanbard@gmail.com> | 2012-06-20 04:20:39 +0000 |
|---|---|---|
| committer | Bill Wendling <isanbard@gmail.com> | 2012-06-20 04:20:39 +0000 |
| commit | 9059390cf0a6d57add00169c28805bb9a59308b6 (patch) | |
| tree | 3ebd511ebf83eb6454680334370a0d00b64ef1bf | |
| parent | a8e0865b7aaeabee8941503842d7978ebcc11f59 (diff) | |
Sphinxify the MakefileGuide document.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@158789 91177308-0d34-0410-b5e6-96231b3b80d8
| -rw-r--r-- | docs/MakefileGuide.html | 1039 | ||||
| -rw-r--r-- | docs/MakefileGuide.rst | 956 | ||||
| -rw-r--r-- | docs/development_process.rst | 5 |
3 files changed, 959 insertions, 1041 deletions
diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html deleted file mode 100644 index 961b1e52d1..0000000000 --- a/docs/MakefileGuide.html +++ /dev/null @@ -1,1039 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title>LLVM Makefile Guide</title> - <link rel="stylesheet" href="_static/llvm.css" type="text/css"> -</head> -<body> - -<h1>LLVM Makefile Guide</h1> - -<ol> - <li><a href="#introduction">Introduction</a></li> - <li><a href="#general">General Concepts</a> - <ol> - <li><a href="#projects">Projects</a></li> - <li><a href="#varvals">Variable Values</a></li> - <li><a href="#including">Including Makefiles</a> - <ol> - <li><a href="#Makefile">Makefile</a></li> - <li><a href="#Makefile.common">Makefile.common</a></li> - <li><a href="#Makefile.config">Makefile.config</a></li> - <li><a href="#Makefile.rules">Makefile.rules</a></li> - </ol> - </li> - <li><a href="#Comments">Comments</a></li> - </ol> - </li> - <li><a href="#tutorial">Tutorial</a> - <ol> - <li><a href="#libraries">Libraries</a> - <ol> - <li><a href="#BCModules">Bitcode Modules</a></li> - <li><a href="#LoadableModules">Loadable Modules</a></li> - </ol> - </li> - <li><a href="#tools">Tools</a> - <ol> - <li><a href="#JIT">JIT Tools</a></li> - </ol> - </li> - <li><a href="#projects">Projects</a></li> - </ol> - </li> - <li><a href="#targets">Targets Supported</a> - <ol> - <li><a href="#all">all</a></li> - <li><a href="#all-local">all-local</a></li> - <li><a href="#check">check</a></li> - <li><a href="#check-local">check-local</a></li> - <li><a href="#clean">clean</a></li> - <li><a href="#clean-local">clean-local</a></li> - <li><a href="#dist">dist</a></li> - <li><a href="#dist-check">dist-check</a></li> - <li><a href="#dist-clean">dist-clean</a></li> - <li><a href="#install">install</a></li> - <li><a href="#preconditions">preconditions</a></li> - <li><a href="#printvars">printvars</a></li> - <li><a href="#reconfigure">reconfigure</a></li> - <li><a href="#spotless">spotless</a></li> - <li><a href="#tags">tags</a></li> - <li><a href="#uninstall">uninstall</a></li> - </ol> - </li> - <li><a href="#variables">Using Variables</a> - <ol> - <li><a href="#setvars">Control Variables</a></li> - <li><a href="#overvars">Override Variables</a></li> - <li><a href="#getvars">Readable Variables</a></li> - <li><a href="#intvars">Internal Variables</a></li> - </ol> - </li> -</ol> - -<div class="doc_author"> - <p>Written by <a href="mailto:reid@x10sys.com">Reid Spencer</a></p> -</div> - -<!-- *********************************************************************** --> -<h2><a name="introduction">Introduction</a></h2> -<!-- *********************************************************************** --> - -<div> - <p>This document provides <em>usage</em> 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 <tt>make</tt>, it is recommended that you read the - <a href="http://www.gnu.org/software/make/manual/make.html">GNU Makefile - Manual</a>.</p> - <p>While this document is rightly part of the - <a href="ProgrammersManual.html">LLVM Programmer's Manual</a>, it is treated - separately here because of the volume of content and because it is often an - early source of bewilderment for new developers.</p> -</div> - -<!-- *********************************************************************** --> -<h2><a name="general">General Concepts</a></h2> -<!-- *********************************************************************** --> - -<div> - <p>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.</p> - -<!-- ======================================================================= --> -<h3><a name="projects">Projects</a></h3> -<div> - <p>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 <tt>llvm/projects</tt> directory. Any directory under <tt>projects</tt> - that has both a <tt>configure</tt> script and a <tt>Makefile</tt> 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 - <tt>llvm/projects</tt> 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.</p> - <p>For complete details on setting up your projects configuration, simply - mimic the <tt>llvm/projects/sample</tt> project or for further details, - consult the <a href="Projects.html">Projects.html</a> page.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="varvalues">Variable Values</a></h3> -<div> - <p>To use the makefile system, you simply create a file named - <tt>Makefile</tt> 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™. -</div> - -<!-- ======================================================================= --> -<h3><a name="including">Including Makefiles</a></h3> -<div> - <p>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.</p> - -<!-- ======================================================================= --> -<h4><a name="Makefile">Makefile</a></h4> -<div> - <p>Each directory to participate in the build needs to have a file named - <tt>Makefile</tt>. This is the file first read by <tt>make</tt>. It has three - sections:</p> - <ol> - <li><a href="#setvars">Settable Variables</a> - Required that must be set - first.</li> - <li><a href="#Makefile.common">include <tt>$(LEVEL)/Makefile.common</tt></a> - - include the LLVM Makefile system. - <li><a href="#overvars">Override Variables</a> - Override variables set by - the LLVM Makefile system. - </ol> -</div> - -<!-- ======================================================================= --> -<h4><a name="Makefile.common">Makefile.common</a></h4> -<div> - <p>Every project must have a <tt>Makefile.common</tt> file at its top source - directory. This file serves three purposes:</p> - <ol> - <li>It includes the project's configuration makefile to obtain values - determined by the <tt>configure</tt> script. This is done by including the - <a href="#Makefile.config"><tt>$(LEVEL)/Makefile.config</tt></a> file.</li> - <li>It specifies any other (static) values that are needed throughout the - project. Only values that are used in all or a large proportion of the - project's directories should be placed here.</li> - <li>It includes the standard rules for the LLVM Makefile system, - <a href="#Makefile.rules"><tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt></a>. - This file is the "guts" of the LLVM Makefile system.</li> - </ol> -</div> - -<!-- ======================================================================= --> -<h4><a name="Makefile.config">Makefile.config</a></h4> -<div> - <p>Every project must have a <tt>Makefile.config</tt> at the top of its - <em>build</em> directory. This file is <b>generated</b> by the - <tt>configure</tt> script from the pattern provided by the - <tt>Makefile.config.in</tt> file located at the top of the project's - <em>source</em> 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 - <tt>$(LLVM_OBJ_ROOT)/Makefile.config</tt>. -</div> - -<!-- ======================================================================= --> -<h4><a name="Makefile.rules">Makefile.rules</a></h4> -<div> - <p>This file, located at <tt>$(LLVM_SRC_ROOT)/Makefile.rules</tt> 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 <tt>make</tt> <a href="#variables">variables</a> that - have been set <em>before</em> <tt>Makefile.rules</tt> is included. -</div> - -</div> - -<!-- ======================================================================= --> -<h3><a name="Comments">Comments</a></h3> -<div> - <p>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 <tt>make</tt>.</p> -</div> - -</div> - -<!-- *********************************************************************** --> -<h2><a name="tutorial">Tutorial</a></h2> -<!-- *********************************************************************** --> -<div> - <p>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.</p> - -<!-- ======================================================================= --> -<h3><a name="libraries">Libraries</a></h3> -<div> - <p>Only a few variable definitions are needed to build a regular library. - Normally, the makefile system will build all the software into a single - <tt>libname.o</tt> (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:</p> - <pre><tt> - LIBRARYNAME = mylib - SHARED_LIBRARY = 1 - ARCHIVE_LIBRARY = 1 - </tt></pre> - <p>says to build a library named "mylib" with both a shared library - (<tt>mylib.so</tt>) and an archive library (<tt>mylib.a</tt>) 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.</p> - <p>The <tt>LOADABLE_MODULE=1</tt> directive can be used in conjunction with - <tt>SHARED_LIBRARY=1</tt> to indicate that the resulting shared library should - be openable with the <tt>dlopen</tt> function and searchable with the - <tt>dlsym</tt> 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 <tt>LOADABLE_MODULE</tt> for - any shared library that you intend to be loaded into an tool via the - <tt>-load</tt> option. See the - <a href="WritingAnLLVMPass.html#makefile">WritingAnLLVMPass.html</a> document - for an example of why you might want to do this. - -<!-- ======================================================================= --> -<h4><a name="BCModules">Bitcode Modules</a></h4> -<div> - <p>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 <a href="#MODULE_NAME">MODULE_NAME</a> - variable. For example:</p> - <pre><tt> - LIBRARYNAME = mylib - BYTECODE_LIBRARY = 1 - MODULE_NAME = mymod - </tt></pre> - <p>will build a module named <tt>mymod.bc</tt> 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. - </p> -</div> - -<!-- ======================================================================= --> -<h4> - <a name="LoadableModules">Loadable Modules</a> -</h4> -<div> - <p>In some situations, you need to create a loadable module. Loadable modules - can be loaded into programs like <tt>opt</tt> or <tt>llc</tt> 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.</p> - <p>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 <tt>MyMod</tt> that uses the LLVM libraries - <tt>LLVMSupport.a</tt> and <tt>LLVMSystem.a</tt>, you would specify:</p> - <pre><tt> - LIBRARYNAME := MyMod - LOADABLE_MODULE := 1 - LINK_COMPONENTS := support system - </tt></pre> - <p>Use of the <tt>LOADABLE_MODULE</tt> facility implies several things:</p> - <ol> - <li>There will be no "lib" prefix on the module. This differentiates it from - a standard shared library of the same name.</li> - <li>The <a href="#SHARED_LIBRARY">SHARED_LIBRARY</a> variable is turned - on.</li> - <li>The <a href="#LINK_LIBS_IN_SHARED">LINK_LIBS_IN_SHARED</a> variable - is turned on.</li> - </ol> - <p>A loadable module is loaded by LLVM via the facilities of libtool's libltdl - library which is part of <tt>lib/System</tt> implementation.</p> -</div> - -</div> - -<!-- ======================================================================= --> -<h3><a name="tools">Tools</a></h3> -<div> - <p>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:</p> - <pre><tt> - TOOLNAME = mytool - USEDLIBS = mylib - LINK_COMPONENTS = support system - </tt></pre> - <p>says that we are to build a tool name <tt>mytool</tt> and that it requires - three libraries: <tt>mylib</tt>, <tt>LLVMSupport.a</tt> and - <tt>LLVMSystem.a</tt>.</p> - <p>Note that two different variables are use to indicate which libraries are - linked: <tt>USEDLIBS</tt> and <tt>LLVMLIBS</tt>. This distinction is necessary - to support projects. <tt>LLVMLIBS</tt> refers to the LLVM libraries found in - the LLVM object directory. <tt>USEDLIBS</tt> refers to the libraries built by - your project. In the case of building LLVM tools, <tt>USEDLIBS</tt> and - <tt>LLVMLIBS</tt> can be used interchangeably since the "project" is LLVM - itself and <tt>USEDLIBS</tt> refers to the same place as <tt>LLVMLIBS</tt>. - </p> - <p>Also note that there are two different ways of specifying a library: with a - <tt>.a</tt> suffix and without. Without the suffix, the entry refers to the - re-linked (.o) file which will include <em>all</em> symbols of the library. - This is useful, for example, to include all passes from a library of passes. - If the <tt>.a</tt> suffix is used then the library is linked as a searchable - library (with the <tt>-l</tt> option). In this case, only the symbols that are - unresolved <em>at that point</em> will be resolved from the library, if they - exist. Other (unreferenced) symbols will not be included when the <tt>.a</tt> - syntax is used. Note that in order to use the <tt>.a</tt> suffix, the library - in question must have been built with the <tt>ARCHIVE_LIBRARY</tt> option set. - </p> - -<!-- ======================================================================= --> -<h4><a name="JIT">JIT Tools</a></h4> -<div> - <p>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:</p> - <pre><tt> - TOOLNAME = my_jit_tool - USEDLIBS = mylib - LINK_COMPONENTS = engine - </tt></pre> - <p>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:</p> - <pre><tt> - cd examples/Fibonacci - make VERBOSE=1 - </tt></pre> -</div> - -</div> - -</div> - -<!-- *********************************************************************** --> -<h2><a name="targets">Targets Supported</a></h2> -<!-- *********************************************************************** --> - -<div> - <p>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).</p> - - <table style="text-align:left"> - <tr> - <th>Target Name</th><th>Implied Targets</th><th>Target Description</th> - </tr> - <tr><td><a href="#all"><tt>all</tt></a></td><td></td> - <td>Compile the software recursively. Default target. - </td></tr> - <tr><td><a href="#all-local"><tt>all-local</tt></a></td><td></td> - <td>Compile the software in the local directory only. - </td></tr> - <tr><td><a href="#check"><tt>check</tt></a></td><td></td> - <td>Change to the <tt>test</tt> directory in a project and run the - test suite there. - </td></tr> - <tr><td><a href="#check-local"><tt>check-local</tt></a></td><td></td> - <td>Run a local test suite. Generally this is only defined in the - <tt>Makefile</tt> of the project's <tt>test</tt> directory. - </td></tr> - <tr><td><a href="#clean"><tt>clean</tt></a></td><td></td> - <td>Remove built objects recursively. - </td></tr> - <tr><td><a href="#clean-local"><tt>clean-local</tt></a></td><td></td> - <td>Remove built objects from the local directory only. - </td></tr> - <tr><td><a href="#dist"><tt>dist</tt></a></td><td>all</td> - <td>Prepare a source distribution tarball. - </td></tr> - <tr><td><a href="#dist-check"><tt>dist-check</tt></a></td><td>all</td> - <td>Prepare a source distribution tarball and check that it builds. - </td></tr> - <tr><td><a href="#dist-clean"><tt>dist-clean</tt></a></td><td>clean</td> - <td>Clean source distribution tarball temporary files. - </td></tr> - <tr><td><a href="#install"><tt>install</tt></a></td><td>all</td> - <td>Copy built objects to installation directory. - </td></tr> - <tr><td><a href="#preconditions"><tt>preconditions</tt></a></td><td>all</td> - <td>Check to make sure configuration and makefiles are up to date. - </td></tr> - <tr><td><a href="#printvars"><tt>printvars</tt></a></td><td>all</td> - <td>Prints variables defined by the makefile system (for debugging). - </td></tr> - <tr><td><a href="#tags"><tt>tags</tt></a></td><td></td> - <td>Make C and C++ tags files for emacs and vi. - </td></tr> - <tr><td><a href="#uninstall"><tt>uninstall</tt></a></td><td></td> - <td>Remove built objects from installation directory. - </td></tr> - </table> - -<!-- ======================================================================= --> -<h3><a name="all">all (default)</a></h3> -<div> - <p>When you invoke <tt>make</tt> 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 <tt>lib</tt> directory, the "all" target will - compile source files and generate libraries. But, in a <tt>tools</tt> - directory, it will link libraries and generate executables.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="all-local">all-local</a></h3> -<div> - <p>This target is the same as <a href="#all">all</a> but it operates only on - the current directory instead of recursively.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="check">check</a></h3> -<div> - <p>This target can be invoked from anywhere within a project's directories - but always invokes the <a href="#check-local"><tt>check-local</tt></a> target - in the project's <tt>test</tt> directory, if it exists and has a - <tt>Makefile</tt>. A warning is produced otherwise. If - <a href="#TESTSUITE"><tt>TESTSUITE</tt></a> is defined on the <tt>make</tt> - command line, it will be passed down to the invocation of - <tt>make check-local</tt> in the <tt>test</tt> directory. The intended usage - for this is to assist in running specific suites of tests. If - <tt>TESTSUITE</tt> is not set, the implementation of <tt>check-local</tt> - should run all normal tests. It is up to the project to define what - different values for <tt>TESTSUTE</tt> will do. See the - <a href="TestingGuide.html">TestingGuide</a> for further details.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="check-local">check-local</a></h3> -<div> - <p>This target should be implemented by the <tt>Makefile</tt> in the project's - <tt>test</tt> directory. It is invoked by the <tt>check</tt> target elsewhere. - Each project is free to define the actions of <tt>check-local</tt> 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.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="clean">clean</a></h3> -<div> - <p>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 <tt>rm -f $(UNSET_VARIABLE)/*</tt> which will attempt - to erase the entire directory structure.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="clean-local">clean-local</a></h3> -<div> - <p>This target does the same thing as <tt>clean</tt> but only for the current - (local) directory.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="dist">dist</a></h3> -<div> - <p>This target builds a distribution tarball. It first builds the entire - project using the <tt>all</tt> 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 <tt>dist-check</tt>).</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="dist-check">dist-check</a></h3> -<div> - <p>This target does the same thing as the <tt>dist</tt> 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.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="dist-clean">dist-clean</a></h3> -<div> - <p>This is a special form of the <tt>clean</tt> clean target. It performs a - normal <tt>clean</tt> but also removes things pertaining to building the - distribution.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="install">install</a></h3> -<div> - <p>This target finalizes shared objects and executables and copies all - libraries, headers, executables and documentation to the directory given - with the <tt>--prefix</tt> option to <tt>configure</tt>. When completed, - the prefix directory will have everything needed to <b>use</b> LLVM. </p> - <p>The LLVM makefiles can generate complete <b>internal</b> documentation - for all the classes by using <tt>doxygen</tt>. By default, this feature is - <b>not</b> 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 <tt>PATH</tt>. You can download - doxygen from - <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc"> - here</a>. -</div> - -<!-- ======================================================================= --> -<h3><a name="preconditions">preconditions</a></h3> -<div> - <p>This utility target checks to see if the <tt>Makefile</tt> in the object - directory is older than the <tt>Makefile</tt> in the source directory and - copies it if so. It also reruns the <tt>configure</tt> script if that needs to - be done and rebuilds the <tt>Makefile.config</tt> file similarly. Users may - overload this target to ensure that sanity checks are run <em>before</em> any - building of targets as all the targets depend on <tt>preconditions</tt>.</p> -</div> - -<!-- ======================================================================= --> -<h3><a name="printvars">printvars</a></h3> -<div> - <p>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. </p> -</div> - -<!-- ======================================================================= --> -<h3><a name="reconfigure">reconfigure</a></h3> -<div> - <p>This utility target will force a reconfigure of LLVM or your project. It - simply runs <tt>$(PROJ_OBJ_ROOT)/config.status --recheck</tt> to rerun the - configuration tests and rebuild the configured files. This isn't generally - useful as the makefiles will reconfigure themselves whenever its necessary. - </p> -</div> - -<!-- ======================================================================= --> -<h3><a name="spotless">spotless</a></h3> -<div> - <p>This utility target, only available when <tt>$(PROJ_OBJ_ROOT)</tt> is not - the same as <tt>$(PROJ_SRC_ROOT)</tt>, will completely clean the - <tt>$(PROJ_OBJ_ROOT)</tt> directory by removing its content entirely and - reconfiguring the directory. This returns the <tt>$(PROJ_OBJ_ROOT)</tt> - directory to a completely fresh state. All content in the directory except - configured files and top-level makefiles will be lost.</p> - <div class="doc_warning"><p>Use with caution.</p></div> -</div> - -<!-- ======================================================================= --> -<h3><a name="tags">tags</a></h3> -<div> - <p>This target will generate a <tt>TAGS</tt> 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. </p> -</div> - -<!-- ======================================================================= --> -<h3><a name="uninstall">uninstall</a></h3> -<div> - <p>This target is the opposite of the <tt>install</tt> 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).</p> -</div> - -</div> - -<!-- *********************************************************************** --> -<h2><a name="variables">Variables</a></h2> -<!-- *********************************************************************** --> -<div> - <p>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.</p> - -<!-- ======================================================================= --> -<h3><a name="setvars">Control Variables</a></h3> -<div> - <p>Variables listed in the table below should be set <em>before</em> the - inclusion of <a href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>. - These variables provide input to the LLVM make system that tell it what to do - for the current directory.</p> - <dl> - <dt><a name="BUILD_ARCHIVE"><tt>BUILD_ARCHIVE</tt></a></dt> - <dd>If set to any value, causes an archive (.a) library to be built.</dd> - <dt><a name="BUILT_SOURCES"><tt>BUILT_SOURCES</tt></a></dt> - <dd>Specifies a set of source files that are generated from other source - files. These sources will be built before any other target processing to - ensure they are present.</dd> - <dt><a name="BYTECODE_LIBRARY"><tt>BYTECODE_LIBRARY</tt></a></dt> - <dd>If set to any value, causes a bitcode library (.bc) to be built.</dd> - <dt><a name="CONFIG_FILES"><tt>CONFIG_FILES</tt></a></dt> - <dd>Specifies a set of configuration files to be installed.</dd> - <dt><a name="DEBUG_SYMBOLS"><tt>DEBUG_SYMBOLS</tt></a></dt> - <dd>If set to any value, causes the build to include debugging - symbols even in optimized objects, libraries and executables. This - alters the flags specified to the compilers and linkers. Debugging - isn't fun in an optimized build, but it is possible.</dd> - <dt><a name="DIRS"><tt>DIRS</tt></a></dt> - <dd>Specifies a set of directories, usually children of the current - directory, that should also be made using the same goal. These directories - will be built serially.</dd> - <dt><a name="DISABLE_AUTO_DEPENDENCIES"><tt>DISABLE_AUTO_DEPENDENCIES</tt></a></dt> - <dd>If set to any value, causes the makefiles to <b>not</b> automatically - generate dependencies when running the compiler. Use of this feature is - discouraged and it may be removed at a later date.</dd> - <dt><a name="ENABLE_OPTIMIZED"><tt>ENABLE_OPTIMIZED</tt></a></dt> - <dd>If set to 1, causes the build to generate optimized objects, - libraries and executables. This alters the flags specified to the compilers - and linkers. Generally debugging won't be a fun experience with an optimized - build.</dd> - <dt><a name="ENABLE_PROFILING"><tt>ENABLE_PROFILING</tt></a></dt> - <dd>If set to 1, causes the build to generate both optimized and - profiled objects, libraries and executables. This alters the flags specified - to the compilers and linkers to ensure that profile data can be collected - from the tools built. Use the <tt>gprof</tt> tool to analyze the output from - the profiled tools (<tt>gmon.out</tt>).</dd> - <dt><a name="DISABLE_ASSERTIONS"><tt>DISABLE_ASSERTIONS</tt></a></dt> - <dd>If set to 1, causes the build to disable assertions, even if - building a debug or profile build. This will exclude all assertion check - code from the build. LLVM will execute faster, but with little help when - things go wrong.</dd> - <dt><a name="EXPERIMENTAL_DIRS"><tt>EXPERIMENTAL_DIRS</tt></a></dt> - <dd>Specify a set of directories that should be built, but if they fail, it - should not cause the build to fail. Note that this should only be used - temporarily while code is being written.</dd> - <dt><a name="EXPORTED_SYMBOL_FILE"><tt>EXPORTED_SYMBOL_FILE</tt></a></dt> - <dd>Specifies the name of a single file that contains a list of the - symbols to be exported by the linker. One symbol per line.</dd> - <dt><a name="EXPORTED_SYMBOL_LIST"><tt>EXPORTED_SYMBOL_LIST</tt></a></dt> - <dd>Specifies a set of symbols to be exported by the linker.</dd> - <dt><a name="EXTRA_DIST"><tt>EXTRA_DIST</tt></a></dt> - <dd>Specifies additional files that should be distributed with LLVM. All - source files, all built sources, all Makefiles, and most documentation files - will be automatically distributed. Use this variable to distribute any - files that are not automatically distributed.</dd> - <dt><a name="KEEP_SYMBOLS"><tt>KEEP_SYMBOLS</tt></a></dt> - <dd>If set to any value, specifies that when linking executables the - makefiles should retain debug symbols in the executable. Normally, symbols - are stripped from the executable.</dd> - <dt><a name="LEVEL"><tt>LEVEL</tt></a><small>(required)</small></dt> - <dd>Specify the level of nesting from the top level. This variable must be - set in each makefile as it is used to find the top level and thus the other - makefiles.</dd> - <dt><a name="LIBRARYNAME"><tt>LIBRARYNAME</tt></a></dt> - <dd>Specify the name of the library to be built. (Required For - Libraries)</dd> - <dt><a name="LINK_COMPONENTS"><tt>LINK_COMPONENTS</tt></a></dt> - <dd>When specified for building a tool, the value of this variable will be - passed to the <tt>llvm-config</tt> tool to generate a link line for the - tool. Unlike <tt>USEDLIBS</tt> and <tt>LLVMLIBS</tt>, not all libraries need - to be specified. The <tt>llvm-config</tt> tool will figure out the library - dependencies and add any libraries that are needed. The <tt>USEDLIBS</tt> - variable can still be used in conjunction with <tt>LINK_COMPONENTS</tt> so - that additional project-specific libraries can be linked with the LLVM - libraries specified by <tt>LINK_COMPONENTS</tt></dd> - <dt><a name="LINK_LIBS_IN_SHARED"><tt>LINK_LIBS_IN_SHARED</tt></a></dt> - <dd>By default, shared library linking will ignore any libraries specified - with the <a href="LLVMLIBS">LLVMLIBS</a> or <a href="USEDLIBS">USEDLIBS</a>. - This prevents shared libs from including things that will be in the LLVM - tool the shared library will be loaded into. However, sometimes it is useful - to link certain libraries into your shared library and this option enables - that feature.</dd> - <dt><a name="LLVMLIBS"><tt>LLVMLIBS</tt></a></dt> - <dd>Specifies the set of libraries from the LLVM $(ObjDir) that will be - linked into the tool or library.</dd> - <dt><a name="LOADABLE_MODULE"><tt>LOADABLE_MODULE</tt></a></dt> - <dd>If set to any value, causes the shared library being built to also be - a loadable module. Loadable modules can be opened with the dlopen() function - and searched with dlsym (or the operating system's equivalent). Note that - setting this variable without also setting <tt>SHARED_LIBRARY</tt> will have - no effect.</dd> - <dt><a name="MODULE_NAME"><tt>MODULE_NAME</tt></a></dt> - <dd>Specifies the name of a bitcode module to be created. A bitcode - module can be specified in conjunction with other kinds of library builds - or by itself. It constructs from the sources a single linked bitcode - file.</dd> - <dt><a name="NO_INSTALL"><tt>NO_INSTALL</tt></a></dt> - <dd>Specifies that the build products of the directory should not be - installed but should be built even if the <tt>install</tt> target is given. - This is handy for directories that build libraries or tools that are only - used as part of the build process, such as code generators (e.g. - <tt>tblgen</tt>).</dd> - <dt><a name="OPTIONAL_DIRS"><tt>OPTIONAL_DIRS</tt></a></dt> - <dd>Specify a set of directories that may be built, if they exist, but its - not an error for them not to exist.</dd> - <dt><a name="PARALLEL_DIRS"><tt>PARALLEL_DIRS</tt></a></dt> - <dd>Specify a set of directories to build recursively and in parallel if - the -j option was used with <tt>make</tt>.</dd> - <dt><a name="SHARED_LIBRARY"><tt>SHARED_LIBRARY</tt></a></dt> - <dd>If set to any value, causes a shared library (.so) to be built in - addition to any other kinds of libraries. Note that this option will cause - all source files to be built twice: once with options for position - independent code and once without. Use it only where you really need a - shared library.</dd> - <dt><a name="SOURCES"><tt>SOURCES</tt><small>(optional)</small></a></dt> - <dd>Specifies the list of source files in the current directory to be - built. Source files of any type may be specified (programs, documentation, - config files, etc.). If not specified, the makefile system will infer the - set of source files from the files present in the current directory.</dd> - <dt><a name="SUFFIXES"><tt>SUFFIXES</tt></a></dt> - <dd>Specifies a set of filename suffixes that occur in suffix match rules. - Only set this if your local <tt>Makefile</tt> specifies additional suffix - match rules.</dd> - <dt><a name="TARGET"><tt>TARGET</tt></a></dt> - <dd>Specifies the name of the LLVM code generation target that the - current directory builds. Setting this variable enables additional rules to - build <tt>.inc</tt> files from <tt>.td</tt> files. </dd> - <dt><a name="TESTSUITE"><tt>TESTSUITE</tt></a></dt> - <dd>Specifies the directory of tests to run in <tt>llvm/test</tt>.</dd> - <dt><a name="TOOLNAME"><tt>TOOLNAME</tt></a></dt> - <dd>Specifies the name of the tool that the current directory should - build.</dd> - <dt><a name="TOOL_VERBOSE"><tt>TOOL_VERBOSE</tt></a></dt> - <dd>Implies VERBOSE and also tells each tool invoked to be verbose. This is - handy when you're trying to see the sub-tools invoked by each tool invoked - by the makefile. For example, this will pass <tt>-v</tt> to the GCC - compilers which causes it to print out the command lines it uses to invoke - sub-tools (compiler, assembler, linker).</dd> - <dt><a name="USEDLIBS"><tt>USEDLIBS</tt></a></dt> - <dd>Specifies the list of project libraries that will be linked into the - tool or library.</dd> - <dt><a name="VERBOSE"><tt>VERBOSE</tt></a></dt> - <dd>Tells the Makefile system to produce detailed output of what it is doing - instead of just summary comments. This will generate a LOT of output.</dd> - </dl> -</div> - -<!-- ======================================================================= --> -<h3><a name="overvars">Override Variables</a></h3> -<div> - <p>Override variables can be used to override the default - values provided by the LLVM makefile system. These variables can be set in - several ways:</p> - <ul> - <li>In the environment (e.g. setenv, export) -- not recommended.</li> - <li>On the <tt>make</tt> command line -- recommended.</li> - <li>On the <tt>configure</tt> command line</li> - <li>In the Makefile (only <em>after</em> the inclusion of <a - href="#Makefile.common"><tt>$(LEVEL)/Makefile.common</tt></a>).</li> - </ul> - <p>The override variables are given below:</p> - <dl> - <dt><a name="AR"><tt>AR</tt></a> <small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>ar</tt> tool.</dd> - <dt><a name="PROJ_OBJ_DIR"><tt>PROJ_OBJ_DIR</tt></a></dt> - <dd>The directory into which the products of build rules will be placed. - This might be the same as - <a href="#PROJ_SRC_DIR"><tt>PROJ_SRC_DIR</tt></a> but typically is - not.</dd> - <dt><a name="PROJ_SRC_DIR"><tt>PROJ_SRC_DIR</tt></a></dt> - <dd>The directory which contains the source files to be built.</dd> - <dt><a name="BUILD_EXAMPLES"><tt>BUILD_EXAMPLES</tt></a></dt> - <dd>If set to 1, build examples in <tt>examples</tt> and (if building - Clang) <tt>tools/clang/examples</tt> directories.</dd> - <dt><a name="BZIP2"><tt>BZIP2</tt></a><small>(configured)</small></dt> - <dd>The path to the <tt>bzip2</tt> tool.</dd> - <dt><a name="CC"><tt>CC</tt></a><small>(configured)</small></dt> - <dd>The path to the 'C' compiler.</dd> - <dt><a name="CFLAGS"><tt>CFLAGS</tt></a></dt> - <dd>Additional flags to be passed to the 'C' compiler.</dd> - <dt><a name="CXX"><tt>CXX</tt></a></dt> - <dd>Specifies the path to the C++ compiler.</dd> - <dt><a name="CXXFLAGS"><tt>CXXFLAGS</tt></a></dt> - <dd>Additional flags to be passed to the C++ compiler.</dd> - <dt><a name="DATE"><tt>DATE<small>(configured)</small></tt></a></dt> - <dd>Specifies the path to the <tt>date</tt> program or any program that can - generate the current date and time on its standard output</dd> - <dt><a name="DOT"><tt>DOT</tt></a><small>(configured)</small></dt> - <dd>Specifies the path to the <tt>dot</tt> tool or <tt>false</tt> if there - isn't one.</dd> - <dt><a name="ECHO"><tt>ECHO</tt></a><small>(configured)</small></dt> - <dd>Specifies the path to the <tt>echo</tt> tool for printing output.</dd> - <dt><a name="EXEEXT"><tt>EXEEXT</tt></a><small>(configured)</small></dt> - <dd>Provides the extension to be used on executables built by the makefiles. - The value may be empty on platforms that do not use file extensions for - executables (e.g. Unix).</dd> - <dt><a name="INSTALL"><tt>INSTALL</tt></a><small>(configured)</small></dt> - <dd>Specifies the path to the <tt>install</tt> tool.</dd> - <dt><a name="LDFLAGS"><tt>LDFLAGS</tt></a><small>(configured)</small></dt> - <dd>Allows users to specify additional flags to pass to the linker.</dd> - <dt><a name="LIBS"><tt>LIBS</tt></a><small>(configured)</small></dt> - <dd>The list of libraries that should be linked with each tool.</dd> - <dt><a name="LIBTOOL"><tt>LIBTOOL</tt></a><small>(configured)</small></dt> - <dd>Specifies the path to the <tt>libtool</tt> tool. This tool is renamed - <tt>mklib</tt> by the <tt>configure</tt> script and always located in the - <dt><a name="LLVMAS"><tt>LLVMAS</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>llvm-as</tt> tool.</dd> - <dt><a name="LLVMCC"><tt>LLVMCC</tt></a></dt> - <dd>Specifies the path to the LLVM capable compiler.</dd> - <dt><a name="LLVMCXX"><tt>LLVMCXX</tt></a></dt> - <dd>Specifies the path to the LLVM C++ capable compiler.</dd> - <dt><a name="LLVMGCC"><tt>LLVMGCC</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the LLVM version of the GCC 'C' Compiler</dd> - <dt><a name="LLVMGXX"><tt>LLVMGXX</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the LLVM version of the GCC C++ Compiler</dd> - <dt><a name="LLVMLD"><tt>LLVMLD</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the LLVM bitcode linker tool</dd> - <dt><a name="LLVM_OBJ_ROOT"><tt>LLVM_OBJ_ROOT</tt></a><small>(configured) - </small></dt> - <dd>Specifies the top directory into which the output of the build is - placed.</dd> - <dt><a name="LLVM_SRC_ROOT"><tt>LLVM_SRC_ROOT</tt></a><small>(configured) - </small></dt> - <dd>Specifies the top directory in which the sources are found.</dd> - <dt><a name="LLVM_TARBALL_NAME"><tt>LLVM_TARBALL_NAME</tt></a> - <small>(configured)</small></dt> - <dd>Specifies the name of the distribution tarball to create. This is - configured from the name of the project and its version number.</dd> - <dt><a name="MKDIR"><tt>MKDIR</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>mkdir</tt> tool that creates - directories.</dd> - <dt><a name="ONLY_TOOLS"><tt>ONLY_TOOLS</tt></a></dt> - <dd>If set, specifies the list of tools to build.</dd> - <dt><a name="PLATFORMSTRIPOPTS"><tt>PLATFORMSTRIPOPTS</tt></a></dt> - <dd>The options to provide to the linker to specify that a stripped (no - symbols) executable should be built.</dd> - <dt><a name="RANLIB"><tt>RANLIB</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>ranlib</tt> tool.</dd> - <dt><a name="RM"><tt>RM</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>rm</tt> tool.</dd> - <dt><a name="SED"><tt>SED</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>sed</tt> tool.</dd> - <dt><a name="SHLIBEXT"><tt>SHLIBEXT</tt></a><small>(configured)</small></dt> - <dd>Provides the filename extension to use for shared libraries.</dd> - <dt><a name="TBLGEN"><tt>TBLGEN</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>tblgen</tt> tool.</dd> - <dt><a name="TAR"><tt>TAR</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>tar</tt> tool.</dd> - <dt><a name="ZIP"><tt>ZIP</tt></a><small>(defaulted)</small></dt> - <dd>Specifies the path to the <tt>zip</tt> tool.</dd> - </dl> -</div> - -<!-- ======================================================================= --> -<h3><a name="getvars">Readable Variables</a></h3> -<div> - <p>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.</p> - <dl> - <dt><a name="bindir"><tt>bindir</tt></a></dt> - <dd>The directory into which executables will ultimately be installed. This - value is derived from the <tt>--prefix</tt> option given to - <tt>configure</tt>.</dd> - <dt><a name="BuildMode"><tt>BuildMode</tt></a></dt> - <dd>The name of the type of build being performed: Debug, Release, or - Profile</dd> - <dt><a name="bitcode_libdir"><tt>bytecode_libdir</tt></a></dt> - <dd>The directory into which bitcode libraries will ultimately be - installed. This value is derived from the <tt>--prefix</tt> option given to - <tt>configure</tt>.</dd> - <dt><a name="ConfigureScriptFLAGS"><tt>ConfigureScriptFLAGS</tt></a></dt> - <dd>Additional flags given to the <tt>configure</tt> script when - reconfiguring.</dd> - <dt><a name="DistDir"><tt>DistDir</tt></a></dt> - <dd>The <em>current</em> directory for which a distribution copy is being - made.</dd> - <dt><a name="Echo"><tt>Echo</tt></a></dt> - <dd>The LLVM Makefile System output command. This provides the - <tt>llvm[n]</tt> prefix and starts with @ so the command itself is not - printed by <tt>make</tt>.</dd> - <dt><a name="EchoCmd"><tt>EchoCmd</tt></a></dt> - <dd> Same as <a href="#Echo"><tt>Echo</tt></a> but without the leading @. - </dd> - <dt><a name="includedir"><tt>includedir</tt></a></dt> - <dd>The directory into which include files will ultimately be installed. - This value is derived from the <tt>--prefix</tt> option given to - <tt>configure</tt>.</dd> - <dt><a name="libdir"><tt>libdir</tt></a></dt><dd></dd> - <dd>The directory into which native libraries will ultimately be installed. - This value is derived from the <tt>--prefix</tt> option given to - <tt>configure</tt>.</dd> - <dt><a name="LibDir"><tt>LibDir</tt></a></dt> - <dd>The configuration specific directory into which libraries are placed - before installation.</dd> - <dt><a name="MakefileConfig"><tt>MakefileConfig</tt></a></dt> - <dd>Full path of the <tt>Makefile.config</tt> file.</dd> - <dt><a name="MakefileConfigIn"><tt>MakefileConfigIn</tt></a></dt> - <dd>Full path of the <tt>Makefile.config.in</tt> file.</dd> - <dt><a name="ObjDir"><tt>ObjDir</tt></a></dt> - <dd>The configuration and directory specific directory where build objects - (compilation results) are placed.</dd> - <dt><a name="SubDirs"><tt>SubDirs</tt></a></dt> - <dd>The complete list of sub-directories of the current directory as - specified by other variables.</dd> - <dt><a name="Sources"><tt>Sources</tt></a></dt> - <dd>The complete list of source files.</dd> - <dt><a name="sysconfdir"><tt>sysconfdir</tt></a></dt> - <dd>The directory into which configuration files will ultimately be - installed. This value is derived from the <tt>--prefix</tt> option given to - <tt>configure</tt>.</dd> - <dt><a name="ToolDir"><tt>ToolDir</tt></a></dt> - <dd>The configuration specific directory into which executables are placed - before they are installed.</dd> - <dt><a name="TopDistDir"><tt>TopDistDir</tt></a></dt> - <dd>The top most directory into which the distribution files are copied. - </dd> - <dt><a name="Verb"><tt>Verb</tt></a></dt> - <dd>Use this as the first thing on your build script lines to enable or - disable verbose mode. It expands to either an @ (quiet mode) or nothing - (verbose mode). </dd> - </dl> -</div> - -<!-- ======================================================================= --> -<h3><a name="intvars">Internal Variables</a></h3> -<div> - <p>Variables listed below are used by the LLVM Makefile System - and considered internal. You should not use these variables under any - circumstances.</p> - <p><tt> - 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 - </tt></p> -</div> - -</div> - -<!-- *********************************************************************** --> -<hr> -<address> - <a href="http://jigsaw.w3.org/css-validator/check/referer"><img - src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> - <a href="http://validator.w3.org/check/referer"><img - src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> - - <a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br> - <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> - Last modified: $Date$ -</address> -</body> -</html> diff --git a/docs/MakefileGuide.rst b/docs/MakefileGuide.rst new file mode 100644 index 0000000000..d2bdd24a9e --- /dev/null +++ b/docs/MakefileGuide.rst @@ -0,0 +1,956 @@ +.. _makefile_guide: + +=================== +LLVM Makefile Guide +=================== + +.. contents:: + :local: + +Introduction +============ + +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 +<http://www.gnu.org/software/make/manual/make.html>`_. + +While this document is rightly part of the `LLVM Programmer's +Manual <ProgrammersManual.html>`_, it is treated separately here because of the +volume of content and because it is often an early source of bewilderment for +new developers. + +General Concepts +================ + +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. + +Projects +-------- + +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 <Projects.html>`_ page. + +Variable Values +--------------- + +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™. + +Including Makefiles +------------------- + +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. + +``Makefile`` +^^^^^^^^^^^^ + +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: + +#. Settable Variables --- Required that must be set first. +#. ``include $(LEVEL)/Makefile.common`` --- include the LLVM Makefile system. +#. Override Variables --- Override variables set by the LLVM Makefile system. + +.. _$(LEVEL)/Makefile.common: + +``Makefile.common`` +^^^^^^^^^^^^^^^^^^^ + +Every project must have a ``Makefile.common`` file at its top source +directory. This file serves three purposes: + +#. It includes the project's configuration makefile to obtain values determined + by the ``configure`` script. This is done by including the + `$(LEVEL)/Makefile.config`_ file. + +#. It specifies any other (static) values that are needed throughout the + project. Only values that are used in all or a large proportion of the + project's directories should be placed here. + +#. It includes the standard rules for the LLVM Makefile system, + `$(LLVM_SRC_ROOT)/Makefile.rules`_. This file is the *guts* of the LLVM + ``Makefile`` system. + +.. _$(LEVEL)/Makefile.config: + +``Makefile.config`` +^^^^^^^^^^^^^^^^^^^ + +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``. + +.. _$(LLVM_SRC_ROOT)/Makefile.rules: + +``Makefile.rules`` +^^^^^^^^^^^^^^^^^^ + +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. + +Comments +^^^^^^^^ + +User ``Makefile``\s 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``. + +Tutorial +======== + +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. + +Libraries +--------- + +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: + +.. code-block:: makefile + + 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 <WritingAnLLVMPass.html#makefile>`_ document for an +example of why you might want to do this. + +Bitcode Modules +^^^^^^^^^^^^^^^ + +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: + +.. code-block:: makefile + + 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. + +Loadable Modules +^^^^^^^^^^^^^^^^ + +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: + +.. code-block:: makefile + + LIBRARYNAME := MyMod + LOADABLE_MODULE := 1 + LINK_COMPONENTS := support system + +Use of the ``LOADABLE_MODULE`` facility implies several things: + +#. There will be no "``lib``" prefix on the module. This differentiates it from + a standard shared library of the same name. + +#. The `SHARED_LIBRARY`_ variable is turned on. + +#. The `LINK_LIBS_IN_SHARED`_ variable is turned on. + +A loadable module is loaded by LLVM via the facilities of libtool's libltdl +library which is part of ``lib/System`` implementation. + +Tools +----- + +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: + +.. code-block:: makefile + + 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. + +JIT Tools +^^^^^^^^^ + +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: + +.. code-block:: makefile + + 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: + +.. code-block:: bash + + % cd examples/Fibonacci + % make VERBOSE=1 + +Targets Supported +================= + +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. +================= =============== ================== + +.. _all: + +``all`` (default) +----------------- + +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. + +``all-local`` +------------- + +This target is the same as `all`_ but it operates only on the current directory +instead of recursively. + +``check`` +--------- + +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 `Testing Guide <TestingGuide.html>`_ for further +details. + +``check-local`` +--------------- + +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. + +``clean`` +--------- + +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. + +``clean-local`` +--------------- + +This target does the same thing as ``clean`` but only for the current (local) +directory. + +``dist`` +-------- + +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``). + +``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. + +``dist-clean`` +-------------- + +This is a special form of the ``clean`` clean target. It performs a normal +``clean`` but also removes things pertaining to building the distribution. + +``install`` +----------- + +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 +<http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc>`_. + +``preconditions`` +----------------- + +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``. + +``printvars`` +------------- + +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. + +``reconfigure`` +--------------- + +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. + +``spotless`` +------------ + +.. warning:: + + Use with caution! + +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. + +``tags`` +-------- + +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. + +``uninstall`` +------------- + +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: + +Variables +========= + +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. + +Control 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. + +``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 from other source + files. These sources will be built before any other target processing to + ensure they are present. + +``BYTECODE_LIBRARY`` + If set to any value, causes a bitcode library (.bc) to be built. + +``CONFIG_FILES`` + Specifies a set of configuration files to be installed. + +``DEBUG_SYMBOLS`` + If set to any value, causes the build to include debugging symbols even in + optimized objects, libraries and executables. This alters the flags + specified to the compilers and linkers. Debugging isn't fun in an optimized + build, but it is possible. + +``DIRS`` + Specifies a set of directories, usually children of the current directory, + that should also be made using the same goal. These directories will be + built serially. + +``DISABLE_AUTO_DEPENDENCIES`` + If set to any value, causes the makefiles to **not** automatically generate + dependencies when running the compiler. Use of this feature is discouraged + and it may be removed at a later date. + +``ENABLE_OPTIMIZED`` + If set to 1, causes the build to generate optimized objects, libraries and + executables. This alters the flags specified to the compilers and + linkers. Generally debugging won't be a fun experience with an optimized + build. + +``ENABLE_PROFILING`` + If set to 1, causes the build to generate both optimized and profiled + objects, libraries and executables. This alters the flags specified to the + compilers and linkers to ensure that profile data can be collected from the + tools built. Use the ``gprof`` tool to analyze the output from the profiled + tools (``gmon.out``). + +``DISABLE_ASSERTIONS`` + If set to 1, causes the build to disable assertions, even if building a + debug or profile build. This will exclude all assertion check code from the + build. LLVM will execute faster, but with little help when things go + wrong. + +``EXPERIMENTAL_DIRS`` + Specify a set of directories that should be built, but if they fail, it + should not cause the build to fail. Note that this should only be used + temporarily while code is being written. + +``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. + +``EXPORTED_SYMBOL_LIST`` + Specifies a set of symbols to be exported by the linker. + +``EXTRA_DIST`` + Specifies additional files that should be distributed with LLVM. All source + files, all built sources, all Makefiles, and most documentation files will + be automatically distributed. Use this variable to distribute any files that + are not automatically distributed. + +``KEEP_SYMBOLS`` + If set to any value, specifies that when linking executables the makefiles + should retain debug symbols in the executable. Normally, symbols are + stripped from the executable. + +``LEVEL`` (required) + Specify the level of nesting from the top level. This variable must be set + in each makefile as it is used to find the top level and thus the other + makefiles. + +``LIBRARYNAME`` + Specify the name of the library to be built. (Required For Libraries) + +``LINK_COMPONENTS`` + When specified for building a tool, the value of this variable will be + passed to the ``llvm-config`` tool to generate a link line for the + tool. Unlike ``USEDLIBS`` and ``LLVMLIBS``, not all libraries need to be + specified. The ``llvm-config`` tool will figure out the library dependencies + and add any libraries that are needed. The ``USEDLIBS`` variable can still + be used in conjunction with ``LINK_COMPONENTS`` so that additional + project-specific libraries can be linked with the LLVM libraries specified + by ``LINK_COMPONENTS``. + +.. _LINK_LIBS_IN_SHARED: + +``LINK_LIBS_IN_SHARED`` + By default, shared library linking will ignore any libraries specified with + the `LLVMLIBS`_ or `USEDLIBS`_. This prevents shared libs from including + things that will be in the LLVM tool the shared library will be loaded + into. However, sometimes it is useful to link certain libraries into your + shared library and this option enables that feature. + +.. _LLVMLIBS: + +``LLVMLIBS`` + Specifies the set of libraries from the LLVM ``$(ObjDir)`` that will be + linked into the tool or library. + +``LOADABLE_MODULE`` + If set to any value, causes the shared library being built to also be a + loadable module. Loadable modules can be opened with the dlopen() function + and searched with dlsym (or the operating system's equivalent). Note that + setting this variable without also setting ``SHARED_LIBRARY`` will have no + effect. + +.. _MODULE_NAME: + +``MODULE_NAME`` + Specifies the name of a bitcode module to be created. A bitcode module can + be specified in conjunction with other kinds of library builds or by + itself. It constructs from the sources a single linked bitcode file. + +``NO_INSTALL`` + Specifies that the build products of the directory should not be installed + but should be built even if the ``install`` target is given. This is handy + for directories that build libraries or tools that are only used as part of + the build process, such as code generators (e.g. ``tblgen``). + +``OPTIONAL_DIRS`` + Specify a set of directories that may be built, if they exist, but its not + an error for them not to exist. + +``PARALLEL_DIRS`` + Specify a set of directories to build recursively and in parallel if the + ``-j`` option was used with ``make``. + +.. _SHARED_LIBRARY: + +``SHARED_LIBRARY`` + If set to any value, causes a shared library (``.so``) to be built in + addition to any other kinds of libraries. Note that this option will cause + all source files to be built twice: once with options for position + independent code and once without. Use it only where you really need a + shared library. + +``SOURCES`` (optional) + Specifies the list of source files in the current directory to be + built. Source files of any type may be specified (programs, documentation, + config files, etc.). If not specified, the makefile system will infer the + set of source files from the files present in the current directory. + +``SUFFIXES`` + Specifies a set of filename suffixes that occur in suffix match rules. Only + set this if your local ``Makefile`` specifies additional suffix match + rules. + +``TARGET`` + Specifies the name of the LLVM code generation target that the current + directory builds. Setting this variable enables additional rules to build + ``.inc`` files from ``.td`` files. + +.. _TESTSUITE: + +``TESTSUITE`` + Specifies the directory of tests to run in ``llvm/test``. + +``TOOLNAME`` + Specifies the name of the tool that the current directory should build. + +``TOOL_VERBOSE`` + Implies ``VERBOSE`` and also tells each tool invoked to be verbose. This is + handy when you're trying to see the sub-tools invoked by each tool invoked + by the makefile. For example, this will pass ``-v`` to the GCC compilers + which causes it to print out the command lines it uses to invoke sub-tools + (compiler, assembler, linker). + +.. _USEDLIBS: + +``USEDLIBS`` + Specifies the list of project libraries that will be linked into the tool or + library. + +``VERBOSE`` + Tells the Makefile system to produce detailed output of what it is doing + instead of just summary comments. This will generate a LOT of output. + +Override Variables +------------------ + +Override variables can be used to override the default values provided by the +LLVM makefile system. These variables can be set in several ways: + +* In the environment (e.g. setenv, export) --- not recommended. +* On the ``make`` command line --- recommended. +* On the ``configure`` command line. +* In the Makefile (only *after* the inclusion of `$(LEVEL)/Makefile.common`_). + +The override variables are given below: + +``AR`` (defaulted) + Specifies the path to the ``ar`` tool. + +``PROJ_OBJ_DIR`` + The directory into which the products of build rules will be placed. This + might be the same as `PROJ_SRC_DIR`_ but typically is not. + +.. _PROJ_SRC_DIR: + +``PROJ_SRC_DIR`` + The directory which contains the source files to be built. + +``BUILD_EXAMPLES`` + If set to 1, build examples in ``examples`` and (if building Clang) + ``tools/clang/examples`` directories. + +``BZIP2`` (configured) + The path to the ``bzip2`` tool. + +``CC`` (configured) + The path to the 'C' compiler. + +``CFLAGS`` + Additional flags to be passed to the 'C' compiler. + +``CXX`` + Specifies the path to the C++ compiler. + +``CXXFLAGS`` + Additional flags to be passed to the C++ compiler. + +``DATE`` (configured) + Specifies the path to the ``date`` program or any program that can generate + the current date and time on its standard output. + +``DOT`` (configured) + Specifies the path to the ``dot`` tool or ``false`` if there isn't one. + +``ECHO`` (configured) + Specifies the path to the ``echo`` tool for printing output. + +``EXEEXT`` (configured) + Provides the extension to be used on executables built by the makefiles. + The value may be empty on platforms that do not use file extensions for + executables (e.g. Unix). + +``INSTALL`` (configured) + Specifies the path to the ``install`` tool. + +``LDFLAGS`` (configured) + Allows users to specify additional flags to pass to the linker. + +``LIBS`` (configured) + The list of libraries that should be linked with each tool. + +``LIBTOOL`` (configured) + Specifies the path to the ``libtool`` tool. This tool is renamed ``mklib`` + by the ``configure`` script. + +``LLVMAS`` (defaulted) + Specifies the path to the ``llvm-as`` tool. + +``LLVMCC`` + Specifies the path to the LLVM capable compiler. + +``LLVMCXX`` + Specifies the path to the LLVM C++ capable compiler. + +``LLVMGCC`` (defaulted) + Specifies the path to the LLVM version of the GCC 'C' Compiler. + +``LLVMGXX`` (defaulted) + Specifies the path to the LLVM version of the GCC C++ Compiler. + +``LLVMLD`` (defaulted) + Specifies the path to the LLVM bitcode linker tool + +``LLVM_OBJ_ROOT`` (configured) + Specifies the top directory into which the output of the build is placed. + +``LLVM_SRC_ROOT`` (configured) + Specifies the top directory in which the sources are found. + +``LLVM_TARBALL_NAME`` (configured) + Specifies the name of the distribution tarball to create. This is configured + from the name of the project and its version number. + +``MKDIR`` (defaulted) + Specifies the path to the ``mkdir`` tool that creates directories. + +``ONLY_TOOLS`` + If set, specifies the list of tools to build. + +``PLATFORMSTRIPOPTS`` + The options to provide to the linker to specify that a stripped (no symbols) + executable should be built. + +``RANLIB`` (defaulted) + Specifies the path to the ``ranlib`` tool. + +``RM`` (defaulted) + Specifies the path to the ``rm`` tool. + +``SED`` (defaulted) + Specifies the path to the ``sed`` tool. + +``SHLIBEXT`` (configured) + Provides the filename extension to use for shared libraries. + +``TBLGEN`` (defaulted) + Specifies the path to the ``tblgen`` tool. + +``TAR`` (defaulted) + Specifies the path to the ``tar`` tool. + +``ZIP`` (defaulted) + Specifies the path to the ``zip`` tool. + +Readable Variables +------------------ + +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. + +``bindir`` + The directory into which executables will ultimately be installed. This + value is derived from the ``--prefix`` option given to ``configure``. + +``BuildMode`` + The name of the type of build being performed: Debug, Release, or + Profile. + +``bytecode_libdir`` + The directory into which bitcode libraries will ultimately be installed. + This value is derived from the ``--prefix`` option given to ``configure``. + +``ConfigureScriptFLAGS`` + Additional flags given to the ``configure`` script when reconfiguring. + +``DistDir`` + The *current* directory for which a distribution copy is being made. + +.. _Echo: + +``Echo`` + The LLVM Makefile System output command. This provides the ``llvm[n]`` + prefix and starts with ``@`` so the command itself is not printed by + ``make``. + +``EchoCmd`` + Same as `Echo`_ but without the leading ``@``. + +``includedir`` + The directory into which include files will ultimately be installed. This + value is derived from the ``--prefix`` option given to ``configure``. + +``libdir`` + The directory into which native libraries will ultimately be installed. + This value is derived from the ``--prefix`` option given to + ``configure``. + +``LibDir`` + The configuration specific directory into which libraries are placed before + installation. + +``MakefileConfig`` + Full path of the ``Makefile.config`` file. + +``MakefileConfigIn`` + Full path of the ``Makefile.config.in`` file. + +``ObjDir`` + The configuration and directory specific directory where build objects + (compilation results) are placed. + +``SubDirs`` + The complete list of sub-directories of the current directory as + specified by other variables. + +``Sources`` + The complete list of source files. + +``sysconfdir`` + The directory into which configuration files will ultimately be + installed. This value is derived from the ``--prefix`` option given to + ``configure``. + +``ToolDir`` + The configuration specific directory into which executables are placed + before they are installed. + +``TopDistDir`` + The top most directory into which the distribution files are copied. + +``Verb`` + Use this as the first thing on your build script lines to enable or disable + verbose mode. It expands to either an ``@`` (quiet mode) or nothing (verbose + mode). + +Internal Variables +------------------ + +Variables listed below are used by the LLVM Makefile System and considered +internal. You should not use these variables under any circumstances. + +.. code-block:: makefile + + 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 diff --git a/docs/development_process.rst b/docs/development_process.rst index 5cb7181c64..40eb24d4bf 100644 --- a/docs/development_process.rst +++ b/docs/development_process.rst @@ -6,8 +6,9 @@ Development Process Documentation .. toctree:: :hidden: - Projects CodingStandards + MakefileGuide + Projects \ @@ -29,7 +30,7 @@ Development Process Documentation Describes the LLVMBuild organization and files used by LLVM to specify component descriptions. - * `LLVM Makefile Guide <MakefileGuide.html>`_ + * :ref:`makefile_guide` Describes how the LLVM makefiles work and how to use them. |