diff options
| author | ed <ed@FreeBSD.org> | 2009-06-02 17:52:33 +0000 |
|---|---|---|
| committer | ed <ed@FreeBSD.org> | 2009-06-02 17:52:33 +0000 |
| commit | 3277b69d734b9c90b44ebde4ede005717e2c3b2e (patch) | |
| tree | 64ba909838c23261cace781ece27d106134ea451 /docs/Projects.html | |
| download | FreeBSD-src-3277b69d734b9c90b44ebde4ede005717e2c3b2e.zip FreeBSD-src-3277b69d734b9c90b44ebde4ede005717e2c3b2e.tar.gz | |
Import LLVM, at r72732.
Diffstat (limited to 'docs/Projects.html')
| -rw-r--r-- | docs/Projects.html | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/docs/Projects.html b/docs/Projects.html new file mode 100644 index 0000000..882ce2e --- /dev/null +++ b/docs/Projects.html @@ -0,0 +1,460 @@ +<!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 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: 2009-01-12 22:29:24 +0100 (Mon, 12 Jan 2009) $ +</address> + +</body> +</html> |
