-.. _getting_started:
-
====================================
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``.
* 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
+--------------------------------------------------------------+-----------------+---------------------------------------------+
| `SVN <http://subversion.tigris.org/project_packages.html>`_ | >=1.3 | Subversion access to LLVM\ :sup:`2` |
+--------------------------------------------------------------+-----------------+---------------------------------------------+
-| `DejaGnu <http://savannah.gnu.org/projects/dejagnu>`_ | 1.4.2 | Automated test suite\ :sup:`3` |
-+--------------------------------------------------------------+-----------------+---------------------------------------------+
-| `tcl <http://www.tcl.tk/software/tcltk/>`_ | 8.3, 8.4 | Automated test suite\ :sup:`3` |
-+--------------------------------------------------------------+-----------------+---------------------------------------------+
-| `expect <http://expect.nist.gov/>`_ | 5.38.0 | Automated test suite\ :sup:`3` |
+| `python <http://www.python.org/>`_ | >=2.4 | Automated test suite\ :sup:`3` |
+--------------------------------------------------------------+-----------------+---------------------------------------------+
| `perl <http://www.perl.com/download.csp>`_ | >=5.6.0 | Utilities |
+--------------------------------------------------------------+-----------------+---------------------------------------------+
"``make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ...``"
**GCC 3.4.x on X86-64/amd64**: GCC `miscompiles portions of LLVM
-<http://llvm.org/PR1056>`_.
+<http://llvm.org/PR1056>`__.
**GCC 3.4.4 (CodeSourcery ARM 2005q3-2)**: this compiler miscompiles LLVM when
building with optimizations enabled. It appears to work with "``make
share the problem.
**GCC 4.1.1 on X86-64/amd64**: GCC `miscompiles portions of LLVM
-<http://llvm.org/PR1063>`_ when compiling llvm itself into 64-bit code. LLVM
+<http://llvm.org/PR1063>`__ when compiling llvm itself into 64-bit code. LLVM
will appear to mostly work but will be buggy, e.g. failing portions of its
testsuite.
erroneous and the linkage is correct. These messages disappear using ld 2.17.
**GNU binutils 2.17**: Binutils 2.17 contains `a bug
-<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`_ which causes huge link
+<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link
times (minutes instead of seconds) when building LLVM. We recommend upgrading
to a newer version (2.17.50.0.4 or later).
**GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug
-<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`_ which causes
+<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes
intermittent failures when building LLVM with position independent code. The
symptom is an error about cyclic dependencies. We recommend upgrading to a
newer version of Gold.
+**Clang 3.0 with libstdc++ 4.7.x**: a few Linux distributions (Ubuntu 12.10,
+Fedora 17) have both Clang 3.0 and libstdc++ 4.7 in their repositories. Clang
+3.0 does not implement a few builtins that are used in this library. We
+recommend using the system GCC to compile LLVM and Clang in this case.
+
+**Clang 3.0 on Mageia 2**. There's a packaging issue: Clang can not find at
+least some (``cxxabi.h``) libstdc++ headers.
+
.. _Getting Started with LLVM:
Getting Started with LLVM
Binary release of the llvm-gcc-4.2 front end for a specific platform.
+.. _checkout:
+
Checkout LLVM from Subversion
-----------------------------
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:: 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:: bash
+.. code-block:: console
% git clone http://llvm.org/git/llvm.git
If you want to check out clang too, run:
-.. code:: 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:: 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:: bash
+.. code-block:: console
% git diff --check master..mybranch
The easiest way to generate a patch is as below:
-.. code:: 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:: 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:: bash
+.. code-block:: console
% git format-patch --attach master..mybranch --stdout | git imap-send
Then, your .git/config should have [imap] sections.
-.. code:: 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:: 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:: 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.
+
+For those who wish to be able to update an llvm repo in a simpler fashion,
+consider placing the following git script in your path under the name
+``git-svnup``:
+
+.. code-block:: bash
+
+ #!/bin/bash
+
+ STATUS=$(git status -s | grep -v "??")
+
+ if [ ! -z "$STATUS" ]; then
+ STASH="yes"
+ git stash >/dev/null
+ fi
+
+ git fetch
+ OLD_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+ git checkout master 2> /dev/null
+ git svn rebase -l
+ git checkout $OLD_BRANCH 2> /dev/null
+
+ if [ ! -z $STASH ]; then
+ git stash pop >/dev/null
+ fi
+
+Then to perform the aforementioned update steps go into your source directory
+and just type ``git-svnup`` or ``git svnup`` and everything will just work.
+
+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:: 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:: bash
+ .. code-block:: console
% cd OBJ_ROOT
#. Run the ``configure`` script located in the LLVM source tree:
- .. code:: 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:: bash
+.. code-block:: console
% gmake
parallel build options provided by GNU Make. For example, you could use the
command:
-.. code:: 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:: bash
+ .. code-block:: console
% cd OBJ_ROOT
* Run the ``configure`` script found in the LLVM source directory:
- .. code:: 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:: 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:: 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:
#. First, create a simple C file, name it 'hello.c':
- .. code:: c
+ .. code-block:: c
#include <stdio.h>
#. Next, compile the C file into a native executable:
- .. code:: bash
+ .. code-block:: console
% clang hello.c -o hello
#. Next, compile the C file into a LLVM bitcode file:
- .. code:: 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:: bash
+ .. code-block:: console
% ./hello
and
- .. code:: 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:: bash
+ .. code-block:: console
% llvm-dis < hello.bc | less
#. Compile the program to native assembly using the LLC code generator:
- .. code:: bash
+ .. code-block:: console
% llc hello.bc -o hello.s
#. Assemble the native assembly language file into a program:
- .. code:: 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:: bash
+ .. code-block:: console
% ./hello.native
projects / oota-llvm.git / blobdiff