[llvm-commits] [llvm] r158709 - in /llvm/trunk/docs: Projects.html Projects.rst

Bill Wendling isanbard at gmail.com
Tue Jun 19 02:18:34 PDT 2012


Author: void
Date: Tue Jun 19 04:18:34 2012
New Revision: 158709

URL: http://llvm.org/viewvc/llvm-project?rev=158709&view=rev
Log:
First attempt at Sphinx. Convert the Projects.html file to Sphinx format.

Added:
    llvm/trunk/docs/Projects.rst
Removed:
    llvm/trunk/docs/Projects.html

Removed: llvm/trunk/docs/Projects.html
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Projects.html?rev=158708&view=auto
==============================================================================
--- llvm/trunk/docs/Projects.html (original)
+++ llvm/trunk/docs/Projects.html (removed)
@@ -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 at uiuc.edu">John Criswell</a><br>
-  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
-  <br>
-  Last modified: $Date$
-</address>
-
-</body>
-</html>

Added: llvm/trunk/docs/Projects.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Projects.rst?rev=158709&view=auto
==============================================================================
--- llvm/trunk/docs/Projects.rst (added)
+++ llvm/trunk/docs/Projects.rst Tue Jun 19 04:18:34 2012
@@ -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.





More information about the llvm-commits mailing list