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

1 files changed, 329 insertions, 0 deletions

diff --git a/docs/Projects.rst b/docs/Projects.rst
new file mode 100644
index 00000000000..3875b302364
--- /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&lt;library base name&gt;</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.