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`` ---
-
- Compile with optimizations enabled (default is NO).
+ * ``--prefix=directory`` --- Specify for *directory* the full pathname of
+ where you want the LLVM tools and libraries to be installed (default
+ ``/usr/local``).
- * ``--enable-assertions`` ---
+ * ``--enable-optimized`` --- Compile with optimizations enabled (default
+ is NO).
- 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``.
* It is also possible to use CMake instead of the makefiles. With CMake it is
- also possible to generate project files for several IDEs: Eclipse CDT4,
+ possible to generate project files for several IDEs: Xcode, Eclipse CDT4,
CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.
* If you get an "internal compiler error (ICE)" or test failures, see
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
Sending patches with Git
^^^^^^^^^^^^^^^^^^^^^^^^
-Please read `Developer Policy <DeveloperPolicy.html#patches>`_, too.
+Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too.
Assume ``master`` points the upstream and ``mybranch`` points your working
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
Then, your .git/config should have [imap] sections.
-.. code-block:: bash
+.. code-block:: ini
[imap]
host = imaps://imap.gmail.com
; in English
folder = "[Gmail]/Drafts"
; example for Japanese, "Modified UTF-7" encoded.
- folder = "[Gmail]/&Tgtm+DBN-"
+ folder = "[Gmail]/&Tgtm+DBN-"
; example for Traditional Chinese
- folder = "[Gmail]/&g0l6Pw-"
+ folder = "[Gmail]/&g0l6Pw-"
For developers to work with git-svn
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
object tree and typing ``gmake`` should rebuild anything in or below that
directory that is out of date.
+This does not apply to building the documentation.
+LLVM's (non-Doxygen) documentation is produced with the
+`Sphinx <http://sphinx-doc.org/>`_ documentation generation system.
+There are some HTML documents that have not yet been converted to the new
+system (which uses the easy-to-read and easy-to-write
+`reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup
+language).
+The generated documentation is built in the ``SRC_ROOT/docs`` directory using
+a special makefile.
+For instructions on how to install Sphinx, see
+`Sphinx Introduction for LLVM Developers
+<http://lld.llvm.org/sphinx_intro.html>`_.
+After following the instructions there for installing Sphinx, build the LLVM
+HTML documentation by doing the following:
+
+.. code-block:: console
+
+ $ cd SRC_ROOT/docs
+ $ make -f Makefile.sphinx
+
+This creates a ``_build/html`` sub-directory with all of the HTML files, not
+just the generated ones.
+This directory corresponds to ``llvm.org/docs``.
+For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
+``llvm.org/docs/SphinxQuickstartTemplate.html``.
+The :doc:`SphinxQuickstartTemplate` is useful when creating a new document.
+
Cross-Compiling LLVM
--------------------
It is possible to cross-compile LLVM itself. That is, you can create LLVM
executables and libraries to be hosted on a platform different from the platform
-where they are build (a Canadian Cross build). To configure a cross-compile,
+where they are built (a Canadian Cross build). To configure a cross-compile,
supply the configure script with ``--build`` and ``--host`` options that are
different. The values of these options must be legal target triples that your
GCC compiler supports.
* 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'
module contains a comprehensive correctness, performance, and benchmarking test
suite for LLVM. It is a separate Subversion module because not every LLVM user
is interested in downloading or building such a comprehensive test suite. For
-further details on this test suite, please see the `Testing
-Guide <TestingGuide.html>`_ document.
+further details on this test suite, please see the :doc:`Testing Guide
+<TestingGuide>` document.
.. _tools:
#. 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
- The second examples shows how to invoke the LLVM JIT, `lli
- <CommandGuide/html/lli.html>`_.
+ The second examples shows how to invoke the LLVM JIT, :doc:`lli
+ <CommandGuide/lli>`.
#. 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