====================================
-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 Libomp (required for OpenMP support):
+
+ * ``cd where-you-want-llvm-to-live``
+ * ``cd llvm/projects``
+ * ``svn co http://llvm.org/svn/llvm-project/openmp/trunk openmp``
+
+#. 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:
+
+ * ``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.
+
+ 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``).
+ * ``-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``).
- * ``--enable-optimized`` --- Compile with optimizations enabled (default
- is NO).
+ * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
+ Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
- * ``--enable-assertions`` --- Compile with assertion checks enabled
- (default is YES).
+ * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled
+ (default is Yes for Debug builds, No for all other build types).
- * ``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.
+ * Run your build tool of choice!
- * ``make check-all`` --- This run the regression tests to ensure everything
- is in working order.
+ * The default target (i.e. ``make``) will build all of LLVM
- * It is also possible to use `CMake <CMake.html>`_ 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.
+ * 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`
* **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.
.. code-block:: console
- % wget ftp://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
+ % 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
.. _GCC wiki entry:
http://gcc.gnu.org/wiki/InstallingGCC
-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.
+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
% 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 libomp (required for OpenMP support), run:
+
+.. code-block:: console
+
+ % cd llvm/projects
+ % git clone http://llvm.org/git/openmp.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
% git config svn-remote.svn.fetch :refs/remotes/origin/master
% git svn rebase -l
-Likewise for compiler-rt and test-suite.
+Likewise for compiler-rt, libomp and test-suite.
To update this clone without generating git-svn tags that conflict with the
upstream Git repo, run:
git checkout master &&
git svn rebase -l)
-Likewise for compiler-rt and test-suite.
+Likewise for compiler-rt, libomp and test-suite.
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
------------------------
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 a 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 "host" 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:
-
- ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
- powerpc, nvptx, r600, sparc, 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 a 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``
-
- 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
+``make docs-llvm-html``
- $ 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``
+ % cmake -G "Unix Makefiles" SRC_ROOT
-Release Builds
+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.
- Tools
+For example:
- ``OBJ_ROOT/Release/bin``
-
- 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
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