-.. _projects:
-
========================
Creating an LLVM Project
========================
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. (You must be using ``Autoconf`` version 2.59 or later
- and your ``aclocal`` version should be 1.9 or later.)
-
-.. code-block:: bash
-
- % cd autoconf
- % ./AutoRegen.sh
-
-#. 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.
+If you want to devise your own build system, studying other projects and LLVM
+``Makefiles`` will probably provide enough information on how to write your own
+``Makefiles``.
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.
+your source tree layout to look similar to the LLVM source tree layout.
Underneath your top level directory, you should have the following directories:
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``
+* LLVM contains regression tests in ``llvm/test``. These tests are run by the
+ :doc:`Lit <CommandGuide/lit>` testing tool. 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.
+ :doc:`TestingGuide` for more details.
* LLVM contains an optional package called ``llvm-test``, which provides
benchmarks and programs that are known to compile with the Clang front
``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.
+ To link dynamic libraries, add ``-l<library base name>`` 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
+ .. code-block:: makefile
- LIBS += -lsample
+ LIBS += -lsample
Note that ``LIBS`` must occur in the Makefile after the inclusion of
``Makefile.common``.
Miscellaneous Variables
-----------------------
-``CFLAGS``
-``CPPFLAGS``
+``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
Libraries
All libraries (static and dynamic) will be stored in
- ``PROJ_OBJ_ROOT/<type>/lib``, where *``type``* is ``Debug``, ``Release``, or
+ ``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.
+ 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>`_.
+<http://lists.llvm.org/pipermail/llvm-dev/>`_.