====================================
-Getting Started with the LLVM System
+Getting Started with the LLVM System
====================================
.. contents::
* ``cd llvm/tools``
* ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
-#. Checkout Compiler-RT:
+#. Checkout Compiler-RT (required to build the sanitizers):
* ``cd where-you-want-llvm-to-live``
* ``cd llvm/projects``
* ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
+#. Checkout libcxx and libcxxabi **[Optional]**:
+
+ * ``cd where-you-want-llvm-to-live``
+ * ``cd llvm/projects``
+ * ``svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx``
+ * ``svn co http://llvm.org/svn/llvm-project/libcxxabi/trunk libcxxabi``
+
#. Get the Test Suite Source Code **[Optional]**
* ``cd where-you-want-llvm-to-live``
#. Configure and build LLVM and Clang:
- * ``cd where-you-want-to-build-llvm``
- * ``mkdir build`` (for building without polluting the source dir)
+ The usual build uses `CMake <CMake.html>`_. If you would rather use
+ autotools, see `Building LLVM with autotools <BuildingLLVMWithAutotools.html>`_.
+
+ * ``cd where you want to build llvm``
+ * ``mkdir build``
* ``cd build``
- * ``../llvm/configure [options]``
- Some common options:
+ * ``cmake -G <generator> [options] <path to llvm sources>``
+
+ Some common generators are:
- * ``--prefix=directory`` --- Specify for *directory* the full pathname of
- where you want the LLVM tools and libraries to be installed (default
- ``/usr/local``).
+ * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles.
+ * ``Ninja`` --- for generating `Ninja <http://martine.github.io/ninja/>`
+ build files.
+ * ``Visual Studio`` --- for generating Visual Studio projects and
+ solutions.
+ * ``Xcode`` --- for generating Xcode projects.
- * ``--enable-optimized`` --- Compile with optimizations enabled (default
- is NO).
+ Some Common options:
- * ``--enable-assertions`` --- Compile with assertion checks enabled
- (default is YES).
+ * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full
+ pathname of where you want the LLVM tools and libraries to be installed
+ (default ``/usr/local``).
- * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
- simultaneously. This builds both LLVM and Clang for Debug+Asserts mode.
- The ``--enable-optimized`` configure option is used to specify a Release
- build.
+ * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
+ Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
- * ``make check-all`` --- This run the regression tests to ensure everything
- is in working order.
+ * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
+ (default is Yes for Debug builds, No for all other build types).
- * It is also possible to use CMake instead of the makefiles. With CMake it is
- possible to generate project files for several IDEs: Xcode, Eclipse CDT4,
- CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.
+ * Run your build tool of choice!
+
+ * The default target (i.e. ``make``) will build all of LLVM
+
+ * The ``check-all`` target (i.e. ``make check-all``) will run the
+ regression tests to ensure everything is in working order.
+
+ * CMake will generate build targets for each tool and library, and most
+ LLVM sub-projects generate their own ``check-<project>`` target.
+
+ * For more information see `CMake <CMake.html>`_
* If you get an "internal compiler error (ICE)" or test failures, see
- `below`.
+ `below`_.
Consult the `Getting Started with LLVM`_ section for detailed information on
configuring and compiling LLVM. See `Setting Up Your Environment`_ for tips
LLVM is known to work on the following host platforms:
================== ===================== =============
-OS Arch Compilers
+OS Arch Compilers
================== ===================== =============
-AuroraUX x86\ :sup:`1` GCC
-Linux x86\ :sup:`1` GCC, Clang
-Linux amd64 GCC, Clang
-Linux ARM\ :sup:`4` GCC, Clang
-Linux PowerPC GCC, Clang
-Solaris V9 (Ultrasparc) GCC
-FreeBSD x86\ :sup:`1` GCC, Clang
-FreeBSD amd64 GCC, Clang
-MacOS X\ :sup:`2` PowerPC GCC
-MacOS X x86 GCC, Clang
-Cygwin/Win32 x86\ :sup:`1, 3` GCC
-Windows x86\ :sup:`1` Visual Studio
-Windows x64 x86-64 Visual Studio
+Linux x86\ :sup:`1` GCC, Clang
+Linux amd64 GCC, Clang
+Linux ARM\ :sup:`4` GCC, Clang
+Linux PowerPC GCC, Clang
+Solaris V9 (Ultrasparc) GCC
+FreeBSD x86\ :sup:`1` GCC, Clang
+FreeBSD amd64 GCC, Clang
+MacOS X\ :sup:`2` PowerPC GCC
+MacOS X x86 GCC, Clang
+Cygwin/Win32 x86\ :sup:`1, 3` GCC
+Windows x86\ :sup:`1` Visual Studio
+Windows x64 x86-64 Visual Studio
================== ===================== =============
.. note::
#. Code generation supported for Pentium processors and up
#. Code generation supported for 32-bit ABI only
#. To use LLVM modules on Win32-based system, you may configure LLVM
- with ``--enable-shared``.
+ with ``-DBUILD_SHARED_LIBS=On`` for CMake builds or ``--enable-shared``
+ for configure builds.
#. MCJIT not working well pre-v7, old JIT engine not supported any more.
Note that you will need about 1-3 GB of space for a full LLVM build in Debug
=========================================================== ============ ==========================================
`GNU Make <http://savannah.gnu.org/projects/make>`_ 3.79, 3.79.1 Makefile/build processor
`GCC <http://gcc.gnu.org/>`_ >=4.7.0 C/C++ compiler\ :sup:`1`
-`python <http://www.python.org/>`_ >=2.5 Automated test suite\ :sup:`2`
+`python <http://www.python.org/>`_ >=2.7 Automated test suite\ :sup:`2`
`GNU M4 <http://savannah.gnu.org/projects/m4>`_ 1.4 Macro processor for configuration\ :sup:`3`
`GNU Autoconf <http://www.gnu.org/software/autoconf/>`_ 2.60 Configuration script builder\ :sup:`3`
`GNU Automake <http://www.gnu.org/software/automake/>`_ 1.9.6 aclocal macro generator\ :sup:`3`
#. If you want to make changes to the configure scripts, you will need GNU
autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You
will also need automake (1.9.6). We only use aclocal from that package.
- #. Optional, adds compression/uncompression capabilities to selected LLVM
+ #. Optional, adds compression / uncompression capabilities to selected LLVM
tools.
Additionally, your compilation host is expected to have the usual plethora of
* **chmod** --- change permissions on a file
* **cat** --- output concatenation utility
* **cp** --- copy files
-* **date** --- print the current date/time
+* **date** --- print the current date/time
* **echo** --- print to standard output
* **egrep** --- extended regular expression search utility
* **find** --- find files/dirs in a file system
* **grep** --- regular expression search utility
* **gzip** --- gzip command for distribution generation
* **gunzip** --- gunzip command for distribution checking
-* **install** --- install directories/files
+* **install** --- install directories/files
* **mkdir** --- create a directory
* **mv** --- move (rename) files
* **ranlib** --- symbol table builder for archive libraries
* Clang 3.1
* GCC 4.7
-* Visual Studio 2012
+* Visual Studio 2013
Anything older than these toolchains *may* work, but will require forcing the
build system with a special option and is not really a supported host platform.
This section mostly applies to Linux and older BSDs. On Mac OS X, you should
have a sufficiently modern Xcode, or you will likely need to upgrade until you
-do. On Windows, just use Visual Studio 2012 as the host compiler, it is
+do. On Windows, just use Visual Studio 2013 as the host compiler, it is
explicitly supported and widely available. FreeBSD 10.0 and newer have a modern
Clang as the system compiler.
The first step is to get a recent GCC toolchain installed. The most common
distribution on which users have struggled with the version requirements is
Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
-the `toolchain testing PPA
-<https://launchpad.net/~ubuntu-toolchain-r/+archive/test>` and use it to
-install a modern GCC. There is a really nice discussions of this on the `ask
-ubuntu stack exchange
-<http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal>`.
-However, not all users can use PPAs and there are many other distros, so it may
-be necessory (or just useful, if you're here you *are* doing compiler
-development after all) to build and install GCC from source. It is also quite
-easy to do these days.
+the `toolchain testing PPA`_ and use it to install a modern GCC. There is
+a really nice discussions of this on the `ask ubuntu stack exchange`_. However,
+not all users can use PPAs and there are many other distributions, so it may be
+necessary (or just useful, if you're here you *are* doing compiler development
+after all) to build and install GCC from source. It is also quite easy to do
+these days.
+
+.. _toolchain testing PPA:
+ https://launchpad.net/~ubuntu-toolchain-r/+archive/test
+.. _ask ubuntu stack exchange:
+ http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal
Easy steps for installing GCC 4.8.2:
.. code-block:: console
- wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
- tar -xvjf gcc-4.8.2.tar.bz2
- cd gcc-4.8.2
- ./contrib/download_prerequisites
- cd ..
- mkdir gcc-4.8.2-build
- cd gcc-4.8.2-build
- %PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
- make -j$(nproc)
- make install
-
-For more details, check out the `excellent GCC wiki entry
-<http://gcc.gnu.org/wiki/InstallingGCC>`, where I got most of this information
-from.
-
-Once you have a GCC toolchain, use it as your host compiler. Things should
-generally "just work". You may need to pass a special linker flag,
-``-Wl,-rpath,$HOME/toolchains/lib`` or some variant thereof to get things to
-find the libstdc++ DSO in this toolchain.
+ % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+ % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2.sig
+ % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
+ % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-4.8.2.tar.bz2.sig`
+ % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi
+ % tar -xvjf gcc-4.8.2.tar.bz2
+ % cd gcc-4.8.2
+ % ./contrib/download_prerequisites
+ % cd ..
+ % mkdir gcc-4.8.2-build
+ % cd gcc-4.8.2-build
+ % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+ % make -j$(nproc)
+ % make install
+
+For more details, check out the excellent `GCC wiki entry`_, where I got most
+of this information from.
+
+.. _GCC wiki entry:
+ http://gcc.gnu.org/wiki/InstallingGCC
+
+Once you have a GCC toolchain, configure your build of LLVM to use the new
+toolchain for your host compiler and C++ standard library. Because the new
+version of libstdc++ is not on the system library search path, you need to pass
+extra linker flags so that it can be found at link time (``-L``) and at runtime
+(``-rpath``). If you are using CMake, this invocation should produce working
+binaries:
+
+.. code-block:: console
+
+ % mkdir build
+ % cd build
+ % CC=$HOME/toolchains/bin/gcc CXX=$HOME/toolchains/bin/g++ \
+ cmake .. -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$HOME/toolchains/lib64 -L$HOME/toolchains/lib64"
+
+If you fail to set rpath, most LLVM binaries will fail on startup with a message
+from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
+found``. This means you need to tweak the -rpath linker flag.
When you build Clang, you will need to give *it* access to modern C++11
standard library in order to use it as your new host in part of a bootstrap.
* ``cd where-you-want-llvm-to-live``
* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
-* Read-Write:``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm``
+* Read-Write: ``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm``
This will create an '``llvm``' directory in the current directory and fully
populate it with the LLVM source code, Makefiles, test directories, and local
following releases are located in the following subdirectories of the '``tags``'
directory:
+* Release 3.4: **RELEASE_34/final**
* Release 3.3: **RELEASE_33/final**
* Release 3.2: **RELEASE_32/final**
* Release 3.1: **RELEASE_31/final**
% cd llvm/tools
% git clone http://llvm.org/git/clang.git
-If you want to check out compiler-rt too, run:
+If you want to check out compiler-rt (required to build the sanitizers), run:
.. code-block:: console
% cd llvm/projects
% git clone http://llvm.org/git/compiler-rt.git
+If you want to check out libcxx and libcxxabi (optional), run:
+
+.. code-block:: console
+
+ % cd llvm/projects
+ % git clone http://llvm.org/git/libcxx.git
+ % git clone http://llvm.org/git/libcxxabi.git
+
If you want to check out the Test Suite Source Code (optional), run:
.. code-block:: console
------------------------
Once checked out from the Subversion repository, the LLVM suite source code must
-be configured via the ``configure`` script. This script sets variables in the
-various ``*.in`` files, most notably ``llvm/Makefile.config`` and
-``llvm/include/Config/config.h``. It also populates *OBJ_ROOT* with the
-Makefiles needed to begin building LLVM.
-
-The following environment variables are used by the ``configure`` script to
-configure the build system:
-
-+------------+-----------------------------------------------------------+
-| Variable | Purpose |
-+============+===========================================================+
-| CC | Tells ``configure`` which C compiler to use. By default, |
-| | ``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 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:
-
-``--enable-optimized``
-
- Enables optimized compilation (debugging symbols are removed and GCC
- optimization flags are enabled). Note that this is the default setting if you
- are using the LLVM distribution. The default behavior of an Subversion
- checkout is to use an unoptimized build (also known as a debug build).
-
-``--enable-debug-runtime``
-
- Enables debug symbols in the runtime libraries. The default is to strip debug
- symbols from the runtime libraries.
-
-``--enable-jit``
-
- Compile the Just In Time (JIT) compiler functionality. This is not available
- on all platforms. The default is dependent on platform, so it is best to
- explicitly enable it if you want it.
-
-``--enable-targets=target-option``
-
- Controls which targets will be built and linked into llc. The default value
- for ``target_options`` is "all" which builds and links all available targets.
- The value "host-only" can be specified to build only a native compiler (no
- cross-compiler targets available). The "native" target is selected as the
- target of the build host. You can also specify a comma separated list of
- target names that you want available in llc. The target names use all lower
- case. The current set of targets is:
-
- ``arm, cpp, hexagon, mips, mipsel, msp430, powerpc, ptx, sparc, spu,
- systemz, x86, x86_64, xcore``.
-
-``--enable-doxygen``
-
- Look for the doxygen program and enable construction of doxygen based
- documentation from the source code. This is disabled by default because
- generating the documentation can take a long time and producess 100s of
- megabytes of output.
-
-``--with-udis86``
-
- LLVM can use external disassembler library for various purposes (now it's used
- only for examining code produced by JIT). This option will enable usage of
- `udis86 <http://udis86.sourceforge.net/>`_ x86 (both 32 and 64 bits)
- disassembler library.
+be configured before being built. For instructions using autotools please see
+`Building LLVM With Autotools <BuildingLLVMWithAutotools.html>`_. The
+recommended process uses CMake. Unlinke the normal ``configure`` script, CMake
+generates the build files in whatever format you request as well as various
+``*.inc`` files, and ``llvm/include/Config/config.h``.
+
+Variables are passed to ``cmake`` on the command line using the format
+``-D<variable name>=<value>``. The following variables are some common options
+used by people developing LLVM.
+
++-------------------------+----------------------------------------------------+
+| Variable | Purpose |
++=========================+====================================================+
+| CMAKE_C_COMPILER | Tells ``cmake`` which C compiler to use. By |
+| | default, this will be /usr/bin/cc. |
++-------------------------+----------------------------------------------------+
+| CMAKE_CXX_COMPILER | Tells ``cmake`` which C++ compiler to use. By |
+| | default, this will be /usr/bin/c++. |
++-------------------------+----------------------------------------------------+
+| CMAKE_BUILD_TYPE | Tells ``cmake`` what type of build you are trying |
+| | to generate files for. Valid options are Debug, |
+| | Release, RelWithDebInfo, and MinSizeRel. Default |
+| | is Debug. |
++-------------------------+----------------------------------------------------+
+| CMAKE_INSTALL_PREFIX | Specifies the install directory to target when |
+| | running the install action of the build files. |
++-------------------------+----------------------------------------------------+
+| LLVM_TARGETS_TO_BUILD | A semicolon delimited list controlling which |
+| | targets will be built and linked into llc. This is |
+| | equivalent to the ``--enable-targets`` option in |
+| | the configure script. The default list is defined |
+| | as ``LLVM_ALL_TARGETS``, and can be set to include |
+| | out-of-tree targets. The default value includes: |
+| | ``AArch64, AMDGPU, ARM, BPF, CppBackend, Hexagon, |
+| | Mips, MSP430, NVPTX, PowerPC, Sparc, SystemZ |
+| | X86, XCore``. |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source |
+| | code This is disabled by default because it is |
+| | slow and generates a lot of output. |
++-------------------------+----------------------------------------------------+
+| LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source |
+| | code. This is disabled by default because it is |
+| | slow and generates a lot of output. |
++-------------------------+----------------------------------------------------+
+| LLVM_BUILD_LLVM_DYLIB | Generate libLLVM.so. This library contains a |
+| | default set of LLVM components that can be |
+| | overridden with ``LLVM_DYLIB_COMPONENTS``. The |
+| | default contains most of LLVM and is defined in |
+| | ``tools/llvm-shlib/CMakelists.txt``. |
++-------------------------+----------------------------------------------------+
+| LLVM_OPTIMIZED_TABLEGEN | Builds a release tablegen that gets used during |
+| | the LLVM build. This can dramatically speed up |
+| | debug builds. |
++-------------------------+----------------------------------------------------+
To configure LLVM, follow these steps:
% cd OBJ_ROOT
-#. Run the ``configure`` script located in the LLVM source tree:
+#. Run the ``cmake``:
.. code-block:: console
- % SRC_ROOT/configure --prefix=/install/path [other options]
+ % cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=prefix=/install/path
+ [other options] SRC_ROOT
Compiling the LLVM Suite Source Code
------------------------------------
-Once you have configured LLVM, you can build it. There are three types of
-builds:
+Unlike with autotools, with CMake your build type is defined at configuration.
+If you want to change your build type, you can re-run cmake with the following
+invocation:
+
+ .. code-block:: console
+
+ % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=type SRC_ROOT
+
+Between runs, CMake preserves the values set for all options. CMake has the
+following build types defined:
-Debug Builds
+Debug
- These builds are the default when one is using an Subversion checkout and
- types ``gmake`` (unless the ``--enable-optimized`` option was used during
- configuration). The build system will compile the tools and libraries with
- debugging information. To get a Debug Build using the LLVM distribution the
- ``--disable-optimized`` option must be passed to ``configure``.
+ These builds are the default. The build system will compile the tools and
+ libraries unoptimized, with debugging information, and asserts enabled.
-Release (Optimized) Builds
+Release
- These builds are enabled with the ``--enable-optimized`` option to
- ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command
- line. For these builds, the build system will compile the tools and libraries
- with GCC optimizations enabled and strip debugging information from the
- libraries and executables it generates. Note that Release Builds are default
- when using an LLVM distribution.
+ For these builds, the build system will compile the tools and libraries
+ with optimizations enabled and not generate debug info. CMakes default
+ optimization level is -O3. This can be configured by setting the
+ ``CMAKE_CXX_FLAGS_RELEASE`` variable on the CMake command line.
-Profile Builds
+RelWithDebInfo
- These builds are for use with profiling. They compile profiling information
- into the code for use with programs like ``gprof``. Profile builds must be
- started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line.
+ These builds are useful when debugging. They generate optimized binaries with
+ debug information. CMakes default optimization level is -O2. This can be
+ configured by setting the ``CMAKE_CXX_FLAGS_RELWITHDEBINFO`` variable on the
+ CMake command line.
Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
directory and issuing the following command:
.. code-block:: console
- % gmake
+ % make
If the build fails, please `check here`_ to see if you are using a version of
GCC that is known not to compile LLVM.
.. code-block:: console
- % gmake -j2
+ % make -j2
There are several special targets which are useful when working with the LLVM
source code:
-``gmake clean``
+``make clean``
Removes all files generated by the build. This includes object files,
generated C/C++ files, libraries, and executables.
-``gmake dist-clean``
-
- Removes everything that ``gmake clean`` does, but also removes files generated
- by ``configure``. It attempts to return the source tree to the original state
- in which it was shipped.
-
-``gmake install``
+``make install``
Installs LLVM header files, libraries, tools, and documentation in a hierarchy
- under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, which
+ under ``$PREFIX``, specified with ``CMAKE_INSTALL_PREFIX``, which
defaults to ``/usr/local``.
-``gmake -C runtime install-bytecode``
+``make docs-llvm-html``
- Assuming you built LLVM into $OBJDIR, when this command is run, it will
- install bitcode libraries into the GCC front end's bitcode library directory.
- If you need to update your bitcode libraries, this is the target to use once
- you've built them.
-
-Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
-these ``make`` targets and descriptions of other targets available.
-
-It is also possible to override default values from ``configure`` by declaring
-variables on the command line. The following are some examples:
-
-``gmake ENABLE_OPTIMIZED=1``
-
- Perform a Release (Optimized) build.
-
-``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
-
- Perform a Release (Optimized) build without assertions enabled.
-
-``gmake ENABLE_OPTIMIZED=0``
-
- Perform a Debug build.
-
-``gmake ENABLE_PROFILING=1``
-
- Perform a Profiling build.
-
-``gmake VERBOSE=1``
-
- Print what ``gmake`` is doing on standard output.
-
-``gmake TOOL_VERBOSE=1``
-
- Ask each tool invoked by the makefiles to print out what it is doing on
- the standard output. This also implies ``VERBOSE=1``.
-
-Every directory in the LLVM object tree includes a ``Makefile`` to build it and
-any subdirectories that it contains. Entering any directory inside the LLVM
-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.
+ If configured with ``-DLLVM_ENABLE_SPHINX=On``, this will generate a directory
+ at ``OBJ_ROOT/docs/html`` which contains the HTML formatted documentation.
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 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.
+where they are built (a Canadian Cross build). To generate build files for
+cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can
+define compiler flags and variables used during the CMake test operations.
The result of such a build is executables that are not runnable on on the build
-host (--build option) but can be executed on the compile host (--host option).
+host but can be executed on the target. As an example the following CMake
+invocation can generate build files targeting iOS. This will work on Mac OS X
+with the latest Xcode:
+
+.. code-block:: console
+
+ % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES=“armv7;armv7s;arm64"
+ -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
+ -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off
+ -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options]
+ <PATH_TO_LLVM>
+
+Note: There are some additional flags that need to be passed when building for
+iOS due to limitations in the iOS SDK.
Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
% cd OBJ_ROOT
-* Run the ``configure`` script found in the LLVM source directory:
+* Run ``cmake``:
.. code-block:: console
- % SRC_ROOT/configure
-
-The LLVM build will place files underneath *OBJ_ROOT* in directories named after
-the build type:
-
-Debug Builds with assertions enabled (the default)
-
- Tools
-
- ``OBJ_ROOT/Debug+Asserts/bin``
-
- Libraries
-
- ``OBJ_ROOT/Debug+Asserts/lib``
-
-Release Builds
+ % cmake -G "Unix Makefiles" SRC_ROOT
- Tools
+The LLVM build will create a structure underneath *OBJ_ROOT* that matches the
+LLVM source tree. At each level where source files are present in the source
+tree there will be a corresponding ``CMakeFiles`` directory in the *OBJ_ROOT*.
+Underneath that directory there is another directory with a name ending in
+``.dir`` under which you'll find object files for each source.
- ``OBJ_ROOT/Release/bin``
+For example:
- Libraries
-
- ``OBJ_ROOT/Release/lib``
-
-Profile Builds
-
- Tools
-
- ``OBJ_ROOT/Profile/bin``
-
- Libraries
+ .. code-block:: console
- ``OBJ_ROOT/Profile/lib``
+ % cd llvm_build_dir
+ % find lib/Support/ -name APFloat*
+ lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o
Optional Configuration Items
----------------------------
almost all code exists in libraries, making it very easy to share code among the
different `tools`_.
-``llvm/lib/VMCore/``
+``llvm/lib/IR/``
This directory holds the core LLVM source files that implement core classes
like Instruction and BasicBlock.
code generation. For example, the ``llvm/lib/Target/X86`` directory holds the
X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM
backend.
-
+
``llvm/lib/CodeGen/``
This directory contains the major parts of the code generator: Instruction
This directory contains projects that are not strictly part of LLVM but are
shipped with LLVM. This is also the directory where you should create your own
-LLVM-based projects. See ``llvm/projects/sample`` for an example of how to set
-up your own project.
+LLVM-based projects.
``llvm/runtime``
----------------
The archiver produces an archive containing the given LLVM bitcode files,
optionally with an index for faster lookup.
-
+
``llvm-as``
The assembler transforms the human readable LLVM assembly to LLVM bitcode.
``llvm-link``, not surprisingly, links multiple LLVM modules into a single
program.
-
+
``lli``
``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode
.. code-block:: console
% ./hello
-
+
and
.. code-block:: console
projects / oota-llvm.git / blobdiff