mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-23 03:02:36 +01:00
328 lines
12 KiB
ReStructuredText
328 lines
12 KiB
ReStructuredText
.. _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:
|
|
|
|
1. 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.
|
|
|
|
2. 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``.
|
|
|
|
3. Add your source code and Makefiles to your source tree.
|
|
|
|
4. 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.
|
|
|
|
5. 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
|
|
|
|
6. 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 you're 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 ``-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
|
|
|
|
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://lists.cs.uiuc.edu/pipermail/llvmdev/>`_.
|