Getting Started with the LLVM System
====================================
+.. contents::
+ :local:
+
Overview
========
* ``../llvm/configure [options]``
Some common options:
- * ``--prefix=directory`` ---
-
- Specify for *directory* the full pathname of where you want the LLVM
- tools and libraries to be installed (default ``/usr/local``).
-
- * ``--enable-optimized`` ---
+ * ``--prefix=directory`` --- Specify for *directory* the full pathname of
+ where you want the LLVM tools and libraries to be installed (default
+ ``/usr/local``).
- Compile with optimizations enabled (default is NO).
+ * ``--enable-optimized`` --- Compile with optimizations enabled (default
+ is NO).
- * ``--enable-assertions`` ---
-
- Compile with assertion checks enabled (default is YES).
+ * ``--enable-assertions`` --- Compile with assertion checks enabled
+ (default is YES).
* ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
simultaneously. This builds both LLVM and Clang for Debug+Asserts mode.
- The --enabled-optimized configure option is used to specify a Release
+ The ``--enabled-optimized`` configure option is used to specify a Release
build.
* ``make check-all`` --- This run the regression tests to ensure everything
is in working order.
-
+
* ``make update`` --- This command is used to update all the svn repositories
at once, rather then having to ``cd`` into the individual repositories and
running ``svn update``.
If you would like to get the LLVM test suite (a separate package as of 1.4), you
get it from the Subversion repository:
-.. code-block:: bash
+.. code-block:: console
% cd llvm/projects
% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
mirrors reflect only ``trunk`` for each project. You can do the read-only GIT
clone of LLVM via:
-.. code-block:: bash
+.. code-block:: console
% git clone http://llvm.org/git/llvm.git
If you want to check out clang too, run:
-.. code-block:: bash
+.. code-block:: console
% git clone http://llvm.org/git/llvm.git
% cd llvm/tools
in your clone. To configure ``git pull`` to pass ``--rebase`` by default on the
master branch, run the following command:
-.. code-block:: bash
+.. code-block:: console
% git config branch.master.rebase true
branch, and ``mybranch`` is rebased onto ``master``. At first you may check
sanity of whitespaces:
-.. code-block:: bash
+.. code-block:: console
% git diff --check master..mybranch
The easiest way to generate a patch is as below:
-.. code-block:: bash
+.. code-block:: console
% git diff master..mybranch > /path/to/mybranch.diff
But you may generate patchset with git-format-patch. It generates by-each-commit
patchset. To generate patch files to attach to your article:
-.. code-block:: bash
+.. code-block:: console
% git format-patch --no-attach master..mybranch -o /path/to/your/patchset
If you would like to send patches directly, you may use git-send-email or
git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
-.. code-block:: bash
+.. code-block:: console
% git format-patch --attach master..mybranch --stdout | git imap-send
To set up clone from which you can submit code using ``git-svn``, run:
-.. code-block:: bash
+.. code-block:: console
% git clone http://llvm.org/git/llvm.git
% cd llvm
To update this clone without generating git-svn tags that conflict with the
upstream git repo, run:
-.. code-block:: bash
+.. code-block:: console
% git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees.
% git checkout master
This leaves your working directories on their master branches, so you'll need to
``checkout`` each working branch individually and ``rebase`` it on top of its
-parent branch. (Note: This script is intended for relative newbies to git. If
-you have more experience, you can likely improve on it.)
+parent branch.
+
+To commit back changes via git-svn, use ``dcommit``:
+
+.. code-block:: console
+
+ % git svn dcommit
+
+Note that git-svn will create one SVN commit for each Git commit you have pending,
+so squash and edit each commit before executing ``dcommit`` to make sure they all
+conform to the coding standards and the developers' policy.
+
+On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict,
+please make sure your current branch is up-to-date (via fetch/rebase) before
+proceeding.
The git-svn metadata can get out of sync after you mess around with branches and
``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining
about files with uncommitted changes. The fix is to rebuild the metadata:
-.. code-block:: bash
+.. code-block:: console
% rm -rf .git/svn
% git svn rebase -l
+Please, refer to the Git-SVN manual (``man git-svn``) for more information.
+
Local LLVM Configuration
------------------------
| Variable | Purpose |
+============+===========================================================+
| CC | Tells ``configure`` which C compiler to use. By default, |
-| | ``configure`` will look for the first GCC C compiler in |
-| | ``PATH``. Use this variable to override ``configure``\'s |
-| | default behavior. |
+| | ``configure`` will check ``PATH`` for ``clang`` and GCC C |
+| | compilers (in this order). Use this variable to override |
+| | ``configure``\'s default behavior. |
+------------+-----------------------------------------------------------+
| CXX | Tells ``configure`` which C++ compiler to use. By |
-| | default, ``configure`` will look for the first GCC C++ |
-| | compiler in ``PATH``. Use this variable to override |
-| | ``configure``'s default behavior. |
+| | default, ``configure`` will check ``PATH`` for |
+| | ``clang++`` and GCC C++ compilers (in this order). Use |
+| | this variable to override ``configure``'s default |
+| | behavior. |
+------------+-----------------------------------------------------------+
The following options can be used to set or enable LLVM specific options:
#. Change directory into the object root directory:
- .. code-block:: bash
+ .. code-block:: console
% cd OBJ_ROOT
#. Run the ``configure`` script located in the LLVM source tree:
- .. code-block:: bash
+ .. code-block:: console
% SRC_ROOT/configure --prefix=/install/path [other options]
Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
directory and issuing the following command:
-.. code-block:: bash
+.. code-block:: console
% gmake
parallel build options provided by GNU Make. For example, you could use the
command:
-.. code-block:: bash
+.. code-block:: console
% gmake -j2
After following the instructions there for installing Sphinx, build the LLVM
HTML documentation by doing the following:
-.. code-block:: bash
+.. code-block:: console
$ cd SRC_ROOT/docs
$ make -f Makefile.sphinx
* Change directory to where the LLVM object files should live:
- .. code-block:: bash
+ .. code-block:: console
% cd OBJ_ROOT
* Run the ``configure`` script found in the LLVM source directory:
- .. code-block:: bash
+ .. code-block:: console
% SRC_ROOT/configure
execute LLVM bitcode files directly. To do this, use commands like this (the
first command may not be required if you are already using the module):
-.. code-block:: bash
+.. code-block:: console
% mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
% echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
This allows you to execute LLVM bitcode files directly. On Debian, you can also
use this command instead of the 'echo' command above:
-.. code-block:: bash
+.. code-block:: console
% sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
#. Next, compile the C file into a native executable:
- .. code-block:: bash
+ .. code-block:: console
% clang hello.c -o hello
#. Next, compile the C file into a LLVM bitcode file:
- .. code-block:: bash
+ .. code-block:: console
% clang -O3 -emit-llvm hello.c -c -o hello.bc
#. Run the program in both forms. To run the program, use:
- .. code-block:: bash
+ .. code-block:: console
% ./hello
and
- .. code-block:: bash
+ .. code-block:: console
% lli hello.bc
#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
- .. code-block:: bash
+ .. code-block:: console
% llvm-dis < hello.bc | less
#. Compile the program to native assembly using the LLC code generator:
- .. code-block:: bash
+ .. code-block:: console
% llc hello.bc -o hello.s
#. Assemble the native assembly language file into a program:
- .. code-block:: bash
+ .. code-block:: console
- **Solaris:** % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+ % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris
- **Others:** % gcc hello.s -o hello.native
+ % gcc hello.s -o hello.native # On others
#. Execute the native code program:
- .. code-block:: bash
+ .. code-block:: console
% ./hello.native