diff options
| author | mike-m <mikem.llvm@gmail.com> | 2010-05-06 23:45:43 +0000 |
|---|---|---|
| committer | mike-m <mikem.llvm@gmail.com> | 2010-05-06 23:45:43 +0000 |
| commit | 68cb31901c590cabceee6e6356d62c84142114cb (patch) | |
| tree | 6444bddc975b662fbe47d63cd98a7b776a407c1a /docs/Projects.html | |
| parent | c26ae5ab7e2d65b67c97524e66f50ce86445dec7 (diff) | |
Overhauled llvm/clang docs builds. Closes PR6613.
NOTE: 2nd part changeset for cfe trunk to follow.
*** PRE-PATCH ISSUES ADDRESSED
- clang api docs fail build from objdir
- clang/llvm api docs collide in install PREFIX/
- clang/llvm main docs collide in install
- clang/llvm main docs have full of hard coded destination
assumptions and make use of absolute root in static html files;
namely CommandGuide tools hard codes a website destination
for cross references and some html cross references assume
website root paths
*** IMPROVEMENTS
- bumped Doxygen from 1.4.x -> 1.6.3
- splits llvm/clang docs into 'main' and 'api' (doxygen) build trees
- provide consistent, reliable doc builds for both main+api docs
- support buid vs. install vs. website intentions
- support objdir builds
- document targets with 'make help'
- correct clean and uninstall operations
- use recursive dir delete only where absolutely necessary
- added call function fn.RMRF which safeguards against botched 'rm -rf';
if any target (or any variable is evaluated) which attempts
to remove any dirs which match a hard-coded 'safelist', a verbose
error will be printed and make will error-stop.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103213 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/Projects.html')
| -rw-r--r-- | docs/Projects.html | 460 |
1 files changed, 0 insertions, 460 deletions
diff --git a/docs/Projects.html b/docs/Projects.html deleted file mode 100644 index ada6196be2..0000000000 --- a/docs/Projects.html +++ /dev/null @@ -1,460 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <title>Creating an LLVM Project</title> - <link rel="stylesheet" href="llvm.css" type="text/css"> -</head> -<body> - -<div class="doc_title">Creating an LLVM Project</div> - -<ol> -<li><a href="#overview">Overview</a></li> -<li><a href="#create">Create a project from the Sample Project</a></li> -<li><a href="#source">Source tree layout</a></li> -<li><a href="#makefiles">Writing LLVM-style Makefiles</a> - <ol> - <li><a href="#reqVars">Required Variables</a></li> - <li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li> - <li><a href="#varsBuildLib">Variables for Building Libraries</a></li> - <li><a href="#varsBuildProg">Variables for Building Programs</a></li> - <li><a href="#miscVars">Miscellaneous Variables</a></li> - </ol></li> -<li><a href="#objcode">Placement of object code</a></li> -<li><a href="#help">Further help</a></li> -</ol> - -<div class="doc_author"> - <p>Written by John Criswell</p> -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"><a name="overview">Overview</a></div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>The LLVM build system is designed to facilitate the building of third party -projects that use LLVM header files, libraries, and tools. In order to use -these facilities, a Makefile from a project must do the following things:</p> - -<ol> - <li>Set <tt>make</tt> variables. There are several variables that a Makefile - needs to set to use the LLVM build system: - <ul> - <li><tt>PROJECT_NAME</tt> - The name by which your project is known.</li> - <li><tt>LLVM_SRC_ROOT</tt> - The root of the LLVM source tree.</li> - <li><tt>LLVM_OBJ_ROOT</tt> - The root of the LLVM object tree.</li> - <li><tt>PROJ_SRC_ROOT</tt> - The root of the project's source tree.</li> - <li><tt>PROJ_OBJ_ROOT</tt> - The root of the project's object tree.</li> - <li><tt>PROJ_INSTALL_ROOT</tt> - The root installation directory.</li> - <li><tt>LEVEL</tt> - The relative path from the current directory to the - project's root ($PROJ_OBJ_ROOT).</li> - </ul></li> - <li>Include <tt>Makefile.config</tt> from <tt>$(LLVM_OBJ_ROOT)</tt>.</li> - <li>Include <tt>Makefile.rules</tt> from <tt>$(LLVM_SRC_ROOT)</tt>.</li> -</ol> - -<p>There are two ways that you can set all of these variables:</p> -<ol> - <li>You can write your own Makefiles which hard-code these values.</li> - <li>You can use the pre-made LLVM sample project. This sample project - includes Makefiles, a configure script that can be used to configure the - location of LLVM, and the ability to support multiple object directories - from a single source directory.</li> -</ol> - -<p>This document assumes that you will base your project on the LLVM sample -project found in <tt>llvm/projects/sample</tt>. If you want to devise your own -build system, studying the sample project and LLVM Makefiles will probably -provide enough information on how to write your own Makefiles.</p> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="create">Create a Project from the Sample Project</a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>Follow these simple steps to start your project:</p> - -<ol> -<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your -choosing. You can place it anywhere you like. Rename the directory to match -the name of your project.</li> - -<li> -If you downloaded LLVM using Subversion, remove all the directories named .svn -(and all the files therein) from your project's new source tree. This will -keep Subversion from thinking that your project is inside -<tt>llvm/trunk/projects/sample</tt>.</li> - -<li>Add your source code and Makefiles to your source tree.</li> - -<li>If you want your project to be configured with the <tt>configure</tt> script -then you need to edit <tt>autoconf/configure.ac</tt> as follows: - <ul> - <li><b>AC_INIT</b>. Place the name of your project, its version number and - a contact email address for your project as the arguments to this macro</li> - <li><b>AC_CONFIG_AUX_DIR</b>. If your project isn't in the - <tt>llvm/projects</tt> directory then you might need to adjust this so that - it specifies a relative path to the <tt>llvm/autoconf</tt> directory.</li> - <li><b>LLVM_CONFIG_PROJECT</b>. Just leave this alone.</li> - <li><b>AC_CONFIG_SRCDIR</b>. Specify a path to a file name that identifies - your project; or just leave it at <tt>Makefile.common.in</tt></li> - <li><b>AC_CONFIG_FILES</b>. Do not change.</li> - <li><b>AC_CONFIG_MAKEFILE</b>. Use one of these macros for each Makefile - that your project uses. This macro arranges for your makefiles to be copied - from the source directory, unmodified, to the build directory.</li> - </ul> -</li> - -<li>After updating <tt>autoconf/configure.ac</tt>, regenerate the -configure script with these commands: - -<div class="doc_code"> -<p><tt>% cd autoconf<br> - % ./AutoRegen.sh</tt></p> -</div> - -<p>You must be using Autoconf version 2.59 or later and your aclocal version -should be 1.9 or later.</p></li> - -<li>Run <tt>configure</tt> in the directory in which you want to place -object code. Use the following options to tell your project where it -can find LLVM: - - <dl> - <dt><tt>--with-llvmsrc=<directory></tt></dt> - <dd>Tell your project where the LLVM source tree is located.</dd> - <dt><br><tt>--with-llvmobj=<directory></tt></dt> - <dd>Tell your project where the LLVM object tree is located.</dd> - <dt><br><tt>--prefix=<directory></tt></dt> - <dd>Tell your project where it should get installed.</dd> - </dl> -</ol> - -<p>That's it! Now all you have to do is type <tt>gmake</tt> (or <tt>make</tt> -if your on a GNU/Linux system) in the root of your object directory, and your -project should build.</p> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="source">Source Tree Layout</a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>In order to use the LLVM build system, you will want to organize your -source code so that it can benefit from the build system's features. -Mainly, you want your source tree layout to look similar to the LLVM -source tree layout. The best way to do this is to just copy the -project tree from <tt>llvm/projects/sample</tt> and modify it to meet -your needs, but you can certainly add to it if you want.</p> - -<p>Underneath your top level directory, you should have the following -directories:</p> - -<dl> - <dt><b>lib</b> - <dd> - This subdirectory should contain all of your library source - code. For each library that you build, you will have one - directory in <b>lib</b> that will contain that library's source - code. - - <p> - Libraries can be object files, archives, or dynamic libraries. - The <b>lib</b> directory is just a convenient place for libraries - as it places them all in a directory from which they can be linked - later. - - <dt><b>include</b> - <dd> - This subdirectory should contain any header files that are - global to your project. By global, we mean that they are used - by more than one library or executable of your project. - <p> - By placing your header files in <b>include</b>, they will be - found automatically by the LLVM build system. For example, if - you have a file <b>include/jazz/note.h</b>, then your source - files can include it simply with <b>#include "jazz/note.h"</b>. - - <dt><b>tools</b> - <dd> - This subdirectory should contain all of your source - code for executables. For each program that you build, you - will have one directory in <b>tools</b> that will contain that - program's source code. - <p> - - <dt><b>test</b> - <dd> - This subdirectory should contain tests that verify that your code - works correctly. Automated tests are especially useful. - <p> - Currently, the LLVM build system provides basic support for tests. - The LLVM system provides the following: - <ul> - <li> - LLVM provides a tcl procedure that is used by Dejagnu to run - tests. It can be found in <tt>llvm/lib/llvm-dg.exp</tt>. This - test procedure uses RUN lines in the actual test case to determine - how to run the test. See the <a - href="TestingGuide.html">TestingGuide</a> for more details. You - can easily write Makefile support similar to the Makefiles in - <tt>llvm/test</tt> to use Dejagnu to run your project's tests.<br></li> - <li> - LLVM contains an optional package called <tt>llvm-test</tt> - which provides benchmarks and programs that are known to compile with the - LLVM GCC front ends. You can use these - programs to test your code, gather statistics information, and - compare it to the current LLVM performance statistics. - <br>Currently, there is no way to hook your tests directly into the - <tt>llvm/test</tt> testing harness. You will simply - need to find a way to use the source provided within that directory - on your own. - </ul> -</dl> - -<p>Typically, you will want to build your <b>lib</b> directory first followed by -your <b>tools</b> directory.</p> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="makefiles">Writing LLVM Style Makefiles</a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>The LLVM build system provides a convenient way to build libraries and -executables. Most of your project Makefiles will only need to define a few -variables. Below is a list of the variables one can set and what they can -do:</p> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="reqVars">Required Variables</a> -</div> - -<div class="doc_text"> - -<dl> - <dt>LEVEL - <dd> - This variable is the relative path from this Makefile to the - top directory of your project's source code. For example, if - your source code is in <tt>/tmp/src</tt>, then the Makefile in - <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>. -</dl> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="varsBuildDir">Variables for Building Subdirectories</a> -</div> - -<div class="doc_text"> - -<dl> - <dt>DIRS - <dd> - This is a space separated list of subdirectories that should be - built. They will be built, one at a time, in the order - specified. - <p> - - <dt>PARALLEL_DIRS - <dd> - This is a list of directories that can be built in parallel. - These will be built after the directories in DIRS have been - built. - <p> - - <dt>OPTIONAL_DIRS - <dd> - This is a list of directories that can be built if they exist, - but will not cause an error if they do not exist. They are - built serially in the order in which they are listed. -</dl> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="varsBuildLib">Variables for Building Libraries</a> -</div> - -<div class="doc_text"> - -<dl> - <dt>LIBRARYNAME - <dd> - This variable contains the base name of the library that will - be built. For example, to build a library named - <tt>libsample.a</tt>, LIBRARYNAME should be set to - <tt>sample</tt>. - <p> - - <dt>BUILD_ARCHIVE - <dd> - By default, a library is a <tt>.o</tt> file that is linked - directly into a program. To build an archive (also known as - a static library), set the BUILD_ARCHIVE variable. - <p> - - <dt>SHARED_LIBRARY - <dd> - If SHARED_LIBRARY is defined in your Makefile, a shared - (or dynamic) library will be built. -</dl> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="varsBuildProg">Variables for Building Programs</a> -</div> - -<div class="doc_text"> - -<dl> - <dt>TOOLNAME - <dd> - This variable contains the name of the program that will - be built. For example, to build an executable named - <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>. - <p> - - <dt>USEDLIBS - <dd> - This variable holds a space separated list of libraries that - should be linked into the program. These libraries must either - be LLVM libraries or libraries that come from your <b>lib</b> - directory. The libraries must be specified by their base name. - For example, to link libsample.a, you would set USEDLIBS to - <tt>sample</tt>. - <p> - Note that this works only for statically linked libraries. - <p> - - <dt>LIBS - <dd> - To link dynamic libraries, add <tt>-l<library base name></tt> to - the LIBS variable. The LLVM build system will look in the same places - for dynamic libraries as it does for static libraries. - <p> - For example, to link <tt>libsample.so</tt>, you would have the - following line in your <tt>Makefile</tt>: - <p> - <tt> - LIBS += -lsample - </tt> -</dl> - -</div> - -<!-- ======================================================================= --> -<div class="doc_subsection"> - <a name="miscVars">Miscellaneous Variables</a> -</div> - -<div class="doc_text"> - -<dl> - <dt>ExtraSource - <dd> - This variable contains a space separated list of extra source - files that need to be built. It is useful for including the - output of Lex and Yacc programs. - <p> - - <dt>CFLAGS - <dt>CPPFLAGS - <dd> - This variable can be used to add options to the C and C++ - compiler, respectively. It is typically used to add options - that tell the compiler the location of additional directories - to search for header files. - <p> - It is highly suggested that you append to CFLAGS and CPPFLAGS as - opposed to overwriting them. The master Makefiles may already - have useful options in them that you may not want to overwrite. - <p> -</dl> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="objcode">Placement of Object Code</a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>The final location of built libraries and executables will depend upon -whether you do a Debug, Release, or Profile build.</p> - -<dl> - <dt>Libraries - <dd> - All libraries (static and dynamic) will be stored in - <tt>PROJ_OBJ_ROOT/<type>/lib</tt>, where type is <tt>Debug</tt>, - <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or - profiled build, respectively.<p> - - <dt>Executables - <dd>All executables will be stored in - <tt>PROJ_OBJ_ROOT/<type>/bin</tt>, where type is <tt>Debug</tt>, - <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled - build, respectively. -</dl> - -</div> - -<!-- *********************************************************************** --> -<div class="doc_section"> - <a name="help">Further Help</a> -</div> -<!-- *********************************************************************** --> - -<div class="doc_text"> - -<p>If you have any questions or need any help creating an LLVM project, -the LLVM team would be more than happy to help. You can always post your -questions to the <a -href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers -Mailing List</a>.</p> - -</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:criswell@uiuc.edu">John Criswell</a><br> - <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> - <br> - Last modified: $Date$ -</address> - -</body> -</html> |