diff options
| author | Bill Wendling <isanbard@gmail.com> | 2012-06-19 09:18:34 +0000 |
|---|---|---|
| committer | Bill Wendling <isanbard@gmail.com> | 2012-06-19 09:18:34 +0000 |
| commit | 4caaa1ab8739362899f18635ad5c3b2d85848e95 (patch) | |
| tree | 0a78d3d704e42b20bf0e16d09b4cd930c2f9e6b5 /docs | |
| parent | b51c8e9bb5769ed17261392ff4222ad3a6668285 (diff) | |
| download | llvm-4caaa1ab8739362899f18635ad5c3b2d85848e95.tar.gz llvm-4caaa1ab8739362899f18635ad5c3b2d85848e95.tar.bz2 llvm-4caaa1ab8739362899f18635ad5c3b2d85848e95.tar.xz | |
First attempt at Sphinx. Convert the Projects.html file to Sphinx format.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@158709 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Projects.html | 482 | ||||
| -rw-r--r-- | docs/Projects.rst | 329 |
2 files changed, 329 insertions, 482 deletions
diff --git a/docs/Projects.html b/docs/Projects.html deleted file mode 100644 index 45f6af5711..0000000000 --- a/docs/Projects.html +++ /dev/null @@ -1,482 +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>Creating an LLVM Project</title> - <link rel="stylesheet" href="_static/llvm.css" type="text/css"> -</head> -<body> - -<h1>Creating an LLVM Project</h1> - -<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> - -<!-- *********************************************************************** --> -<h2><a name="overview">Overview</a></h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="create">Create a Project from the Sample Project</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="source">Source Tree Layout</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="makefiles">Writing LLVM Style Makefiles</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- ======================================================================= --> -<h3> - <a name="reqVars">Required Variables</a> -</h3> - -<div> - -<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> - -<!-- ======================================================================= --> -<h3> - <a name="varsBuildDir">Variables for Building Subdirectories</a> -</h3> - -<div> - -<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> - -<!-- ======================================================================= --> -<h3> - <a name="varsBuildLib">Variables for Building Libraries</a> -</h3> - -<div> - -<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> - -<!-- ======================================================================= --> -<h3> - <a name="varsBuildProg">Variables for Building Programs</a> -</h3> - -<div> - -<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 be libraries that - come from your <b>lib</b> directory. The libraries must be - specified without their "lib" prefix. For example, to link - libsample.a, you would set USEDLIBS to - <tt>sample.a</tt>. - <p> - Note that this works only for statically linked libraries. - <p> - - <dt>LLVMLIBS - <dd> - This variable holds a space separated list of libraries that should - be linked into the program. These libraries must be LLVM libraries. - The libraries must be specified without their "lib" prefix. For - example, to link with a driver that performs an IR transformation - you might set LLVMLIBS to this minimal set of libraries - <tt>LLVMSupport.a LLVMCore.a LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a LLVMScalarOpts.a LLVMTarget.a</tt>. - <p> - Note that this works only for statically linked libraries. LLVM is - split into a large number of static libraries, and the list of libraries you - require may be much longer than the list above. To see a full list - of libraries use: - <tt>llvm-config --libs all</tt>. - Using LINK_COMPONENTS as described below, obviates the need to set LLVMLIBS. - <p> - - <dt>LINK_COMPONENTS - <dd>This variable holds a space separated list of components that - the LLVM Makefiles pass to the <tt>llvm-config</tt> tool to generate - a link line for the program. For example, to link with all LLVM - libraries use - <tt>LINK_COMPONENTS = all</tt>. - <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> - <p> - Note that LIBS must occur in the Makefile after the inclusion of Makefile.common. - <p> -</dl> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="miscVars">Miscellaneous Variables</a> -</h3> - -<div> - -<dl> - <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> - -<!-- *********************************************************************** --> -<h2> - <a name="objcode">Placement of Object Code</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> - -<!-- *********************************************************************** --> -<h2> - <a name="help">Further Help</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<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> diff --git a/docs/Projects.rst b/docs/Projects.rst new file mode 100644 index 0000000000..3875b30236 --- /dev/null +++ b/docs/Projects.rst @@ -0,0 +1,329 @@ +.. _projects: + +======================== +Creating an LLVM Project +======================== + +.. contents:: + :local: + +Overview +======== + +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: + +* Set ``make`` variables. There are several variables that a ``Makefile`` needs + to set to use the LLVM build system: + + * ``PROJECT_NAME`` — The name by which your project is known. + * ``LLVM_SRC_ROOT`` — The root of the LLVM source tree. + * ``LLVM_OBJ_ROOT`` — The root of the LLVM object tree. + * ``PROJ_SRC_ROOT`` — The root of the project's source tree. + * ``PROJ_OBJ_ROOT`` — The root of the project's object tree. + * ``PROJ_INSTALL_ROOT`` — The root installation directory. + * ``LEVEL`` — The relative path from the current directory to the + project's root ``($PROJ_OBJ_ROOT)``. + +* Include ``Makefile.config`` from ``$(LLVM_OBJ_ROOT)``. + +* Include ``Makefile.rules`` from ``$(LLVM_SRC_ROOT)``. + +There are two ways that you can set all of these variables: + +* You can write your own ``Makefiles`` which hard-code these values. + +* 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. + +This document assumes that you will base your project on the LLVM sample project +found in ``llvm/projects/sample``. 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``. + +Create a Project from the Sample Project +======================================== + +Follow these simple steps to start your project: + +#. Copy the ``llvm/projects/sample`` directory to any place of your choosing. + You can place it anywhere you like. Rename the directory to match the name + of your project. + +#. 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 + ``llvm/trunk/projects/sample``. + +#. Add your source code and Makefiles to your source tree. + +#. If you want your project to be configured with the ``configure`` script then + you need to edit ``autoconf/configure.ac`` as follows: + + * **``AC_INIT``** — Place the name of your project, its version number + and a contact email address for your project as the arguments to this macro + + * **``AC_CONFIG_AUX_DIR``** — If your project isn't in the + ``llvm/projects`` directory then you might need to adjust this so that it + specifies a relative path to the ``llvm/autoconf`` directory. + + * **``LLVM_CONFIG_PROJECT``** — Just leave this alone. + + * **``AC_CONFIG_SRCDIR``** — Specify a path to a file name that + identifies your project; or just leave it at ``Makefile.common.in``. + + * **``AC_CONFIG_FILES``** — Do not change. + + * **``AC_CONFIG_MAKEFILE``** — 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. + +#. After updating ``autoconf/configure.ac``, regenerate the configure script + with these commands: + +.. code-block:: bash + + % cd autoconf + % ./AutoRegen.sh + + You must be using Autoconf version 2.59 or later and your ``aclocal`` version + should be 1.9 or later. + +#. Run ``configure`` in the directory in which you want to place object code. + Use the following options to tell your project where it can find LLVM: + + ``--with-llvmsrc=<directory>`` + Tell your project where the LLVM source tree is located. + + ``--with-llvmobj=<directory>`` + Tell your project where the LLVM object tree is located. + + ``--prefix=<directory>`` + Tell your project where it should get installed. + +That's it! Now all you have to do is type ``gmake`` (or ``make`` if your on a +GNU/Linux system) in the root of your object directory, and your project should +build. + +Source Tree Layout +================== + +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 +``llvm/projects/sample`` and modify it to meet your needs, but you can certainly +add to it if you want. + +Underneath your top level directory, you should have the following directories: + +**``lib``** + + This subdirectory should contain all of your library source code. For each + library that you build, you will have one directory in **``lib``** that will + contain that library's source code. + + Libraries can be object files, archives, or dynamic libraries. The + **``lib``** directory is just a convenient place for libraries as it places + them all in a directory from which they can be linked later. + +**``include``** + + 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. + + By placing your header files in **``include``**, they will be found + automatically by the LLVM build system. For example, if you have a file + **``include/jazz/note.h``**, then your source files can include it simply + with **``#include "jazz/note.h"``**. + +**``tools``** + + This subdirectory should contain all of your source code for executables. + For each program that you build, you will have one directory in + **``tools``** that will contain that program's source code. + +**``test``** + + This subdirectory should contain tests that verify that your code works + correctly. Automated tests are especially useful. + + Currently, the LLVM build system provides basic support for tests. The LLVM + system provides the following: + +* LLVM provides a ``tcl`` procedure that is used by ``Dejagnu`` to run tests. + It can be found in ``llvm/lib/llvm-dg.exp``. This test procedure uses ``RUN`` + lines in the actual test case to determine how to run the test. See the + `TestingGuide`_TestingGuide.html for more details. You can easily write + Makefile support similar to the Makefiles in ``llvm/test`` to use ``Dejagnu`` + to run your project's tests. + +* LLVM contains an optional package called ``llvm-test``, which provides + benchmarks and programs that are known to compile with the Clang front + end. You can use these programs to test your code, gather statistical + information, and compare it to the current LLVM performance statistics. + + Currently, there is no way to hook your tests directly into the ``llvm/test`` + testing harness. You will simply need to find a way to use the source + provided within that directory on your own. + +Typically, you will want to build your **``lib``** directory first followed by +your **``tools``** directory. + +Writing LLVM Style Makefiles +============================ + +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: + +Required Variables +------------------ + +``LEVEL`` + + 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 ``/tmp/src``, then the ``Makefile`` in ``/tmp/src/jump/high`` + would set ``LEVEL`` to ``"../.."``. + +Variables for Building Subdirectories +------------------------------------- + +``DIRS`` + + This is a space separated list of subdirectories that should be built. They + will be built, one at a time, in the order specified. + +``PARALLEL_DIRS`` + + This is a list of directories that can be built in parallel. These will be + built after the directories in DIRS have been built. + +``OPTIONAL_DIRS`` + + 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. + +Variables for Building Libraries +-------------------------------- + +``LIBRARYNAME`` + + This variable contains the base name of the library that will be built. For + example, to build a library named ``libsample.a``, ``LIBRARYNAME`` should + be set to ``sample``. + +``BUILD_ARCHIVE`` + + By default, a library is a ``.o`` file that is linked directly into a + program. To build an archive (also known as a static library), set the + ``BUILD_ARCHIVE`` variable. + +``SHARED_LIBRARY`` + + If ``SHARED_LIBRARY`` is defined in your Makefile, a shared (or dynamic) + library will be built. + +Variables for Building Programs +------------------------------- + +``TOOLNAME`` + + This variable contains the name of the program that will be built. For + example, to build an executable named ``sample``, ``TOOLNAME`` should be set + to ``sample``. + +``USEDLIBS`` + + This variable holds a space separated list of libraries that should be + linked into the program. These libraries must be libraries that come from + your **``lib``** directory. The libraries must be specified without their + ``lib`` prefix. For example, to link ``libsample.a``, you would set + ``USEDLIBS`` to ``sample.a``. + + Note that this works only for statically linked libraries. + +``LLVMLIBS`` + + This variable holds a space separated list of libraries that should be + linked into the program. These libraries must be LLVM libraries. The + libraries must be specified without their ``lib`` prefix. For example, to + link with a driver that performs an IR transformation you might set + ``LLVMLIBS`` to this minimal set of libraries ``LLVMSupport.a LLVMCore.a + LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a + LLVMScalarOpts.a LLVMTarget.a``. + + Note that this works only for statically linked libraries. LLVM is split + into a large number of static libraries, and the list of libraries you + require may be much longer than the list above. To see a full list of + libraries use: ``llvm-config --libs all``. Using ``LINK_COMPONENTS`` as + described below, obviates the need to set ``LLVMLIBS``. + +``LINK_COMPONENTS`` + + This variable holds a space separated list of components that the LLVM + ``Makefiles`` pass to the ``llvm-config`` tool to generate a link line for + the program. For example, to link with all LLVM libraries use + ``LINK_COMPONENTS = all``. + +``LIBS`` + + 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. + + For example, to link ``libsample.so``, you would have the following line in + your ``Makefile``: + +.. code-block: Makefile + + LIBS += -lsample + +Note that ``LIBS`` must occur in the Makefile after the inclusion of +``Makefile.common``. + +Miscellaneous Variables +----------------------- + +``CFLAGS`` +``CPPFLAGS`` + + 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. + + 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. + +Placement of Object Code +======================== + +The final location of built libraries and executables will depend upon whether +you do a ``Debug``, ``Release``, or ``Profile`` build. + +Libraries + + All libraries (static and dynamic) will be stored in + ``PROJ_OBJ_ROOT/<type>/lib``, where *``type``* is ``Debug``, ``Release``, or + ``Profile`` for a debug, optimized, or profiled build, respectively. + +Executables + + All executables will be stored in ``PROJ_OBJ_ROOT/<type>/bin``, where + *``type``* is ``Debug``, ``Release``, or ``Profile`` for a debug, optimized, + or profiled build, respectively. + +Further Help +============ + +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 `LLVM Developers Mailing List`_http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev. |