[llvm] r232135 - Updating GettingStarted documentation to reference CMake as the preferred way to build LLVM.
Sean Silva
chisophugis at gmail.com
Fri Mar 13 22:45:16 PDT 2015
On Fri, Mar 13, 2015 at 9:07 AM, Chris Bieneman <beanz at apple.com> wrote:
>
> On Mar 13, 2015, at 1:29 AM, Justin Bogner <mail at justinbogner.com> wrote:
>
> Chris Bieneman <beanz at apple.com> writes:
>
> Author: cbieneman
> Date: Thu Mar 12 20:58:14 2015
> New Revision: 232135
>
> URL: http://llvm.org/viewvc/llvm-project?rev=232135&view=rev
> Log:
> Updating GettingStarted documentation to reference CMake as the
> preferred way to build LLVM.
>
> Reviewers: chandlerc, samsonov, echristo
>
> Reviewed By: samsonov
>
> Subscribers: emaste, joker.eph, llvm-commits
>
> Differential Revision: http://reviews.llvm.org/D8046
>
> Added:
> llvm/trunk/docs/BuildingLLVMWithAutotools.rst
> Modified:
> llvm/trunk/docs/GettingStarted.rst
> llvm/trunk/docs/index.rst
>
> Added: llvm/trunk/docs/BuildingLLVMWithAutotools.rst
> URL:
>
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/BuildingLLVMWithAutotools.rst?rev=232135&view=auto
>
> ==============================================================================
> --- llvm/trunk/docs/BuildingLLVMWithAutotools.rst (added)
> +++ llvm/trunk/docs/BuildingLLVMWithAutotools.rst Thu Mar 12 20:58:14 2015
> @@ -0,0 +1,297 @@
> +====================================
> +Building LLVM With Autotools
> +====================================
> +
> +.. contents::
> + :local:
> +
> +Overview
> +========
> +
> +
> +Local LLVM Configuration
> +------------------------
> +
> +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.
> +
> +To configure LLVM, follow these steps:
> +
> +#. Change directory into the object root directory:
> +
> + .. code-block:: console
> +
> + % cd OBJ_ROOT
> +
> +#. Run the ``configure`` script located in the LLVM source tree:
> +
> + .. code-block:: console
> +
> + % SRC_ROOT/configure --prefix=/install/path [other options]
> +
> +Compiling the LLVM Suite Source Code
> +------------------------------------
> +
> +Once you have configured LLVM, you can build it. There are three types of
> +builds:
> +
> +Debug Builds
> +
> + 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``.
> +
> +Release (Optimized) Builds
> +
> + 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.
> +
> +Profile Builds
> +
> + 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.
> +
> +Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
> +directory and issuing the following command:
> +
> +.. code-block:: console
> +
> + % gmake
> +
> +If the build fails, please `check here <GettingStarted.html#check-here>`_
> +to see if you are using a version of GCC that is known not to compile
> LLVM.
> +
> +If you have multiple processors in your machine, you may wish to use some
> of the
> +parallel build options provided by GNU Make. For example, you could use
> the
> +command:
> +
> +.. code-block:: console
> +
> + % gmake -j2
> +
> +There are several special targets which are useful when working with the
> LLVM
> +source code:
> +
> +``gmake 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``
> +
> + Installs LLVM header files, libraries, tools, and documentation in a
> hierarchy
> + under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, 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
> +
> + $ 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`` <http://llvm.org/docs>.
> +For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
> +``llvm.org/docs/SphinxQuickstartTemplate.html``
> <http://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 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.
> +
> +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).
> +
> +Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to
> cross-compile in general
> +<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
> +about cross-compiling.
> +
> +The Location of LLVM Object Files
> +---------------------------------
> +
> +The LLVM build system is capable of sharing a single LLVM source tree
> among
> +several LLVM builds. Hence, it is possible to build LLVM for several
> different
> +platforms or configurations using the same source tree.
> +
> +This is accomplished in the typical autoconf manner:
> +
> +* Change directory to where the LLVM object files should live:
> +
> + .. code-block:: console
> +
> + % cd OBJ_ROOT
> +
> +* Run the ``configure`` script found in the LLVM source directory:
> +
> + .. 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
> +
> + Tools
> +
> + ``OBJ_ROOT/Release/bin``
> +
> + Libraries
> +
> + ``OBJ_ROOT/Release/lib``
> +
> +Profile Builds
> +
> + Tools
> +
> + ``OBJ_ROOT/Profile/bin``
> +
> + Libraries
> +
> + ``OBJ_ROOT/Profile/lib``
>
> Modified: llvm/trunk/docs/GettingStarted.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/GettingStarted.rst?rev=232135&r1=232134&r2=232135&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/GettingStarted.rst (original)
> +++ llvm/trunk/docs/GettingStarted.rst Thu Mar 12 20:58:14 2015
> @@ -61,7 +61,37 @@ Here's the short story for getting up an
> * ``cd llvm/projects``
> * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk
> test-suite``
>
> -#. Configure and build LLVM and Clang:
> +#. Configure and build LLVM and Clang (Recommended process using CMake):
>
>
> The "(Recommended process using CMake)" blurb is just confusing at this
> point. Better to go with something like so I think:
>
> #. Configure and build LLVM and Clang:
>
> The usual build uses `CMake <CMake.html>`_. If you would rather use
> autotools, see `Building LLVM with autotools <...html>`.
>
>
> Good point. I’ll make this change.
>
>
> +
> + * ``cd where you want to build llvm``
> + * ``mkdir build``
> + * ``cd build``
> + * ``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:
> +
> + * ``-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``).
> +
> + * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug,
> + Release, RelWithDebInfo, and MinSizeRel. Default is Debug.
> +
> + * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks
> enabled
> + (default is Yes for Debug builds, No for all other build types).
> +
> + * For more information see `CMake <CMake.html>`_
>
>
> While this is kind of required knowledge to use cmake at all, I find it
> a bit verbose for a getting started section. Could we instead give a
> concrete example of something useful and explain where to learn about
> customization? Ie,
>
> * ``cmake -G Ninja -DCMAKE_BUILD_TYPE=Release <path to llvm sources>``
>
> To use ``make`` or an IDE, or to customize the build type and
> options, see …
>
>
> I actually like it this way. This is consistent with the way the
> documentation was in the past, and there are more concrete examples further
> down.
>
> Anyone from the community want to be a tie breaker?
>
Personally, I find that 99% of my changes to command line flags are
precisely CMAKE_BUILD_TYPE and LLVM_ENABLE_ASSERTIONS, so it makes sense to
cover them here. They are sort of essential for any sort of development
with LLVM. I personally rarely use CMAKE_INSTALL_PREFIX, but I guess other
people do. From my own personal experience, I would mention it last, if at
all, among essential CMake flags.
>
>
> +
> +#. Configure and build LLVM and Clang (Alternate process using configure):
>
>
> Why isn't this just part of the "building with autotools" doc now?
>
>
> I can move that too. I had wanted to keep the most basic documentation in
> GettingStarted, but if we’re going to be pushing CMake I should probably
> move that off too.
>
I would move it off GettingStarted. People "getting started" should not be
using autotools, as it is generally understood to be going away "any day
now" (with Chris's current burst of activity it seems that day may finally
be not too far off) .
Also, the smaller GettingStarted is while still providing the ability to
get started, the better. Basically, I would say that the trial-by-fire way
to know whether something needs to be mentioned is whether somebody
"getting started" needs to know this.
E.g.:
Someone getting started needs to know how to get the code.
Someone getting started needs to know how to build the code (in various
standard configurations).
btw, if you haven't seen it, PR14711, which is sort of out of date now.
-- Sean Silva
>
> -Chris
>
>
> * ``cd where-you-want-to-build-llvm``
> * ``mkdir build`` (for building without polluting the source dir)
> @@ -87,11 +117,6 @@ Here's the short story for getting up an
> * ``make check-all`` --- This run the regression tests to ensure
> everything
> is in working order.
>
> - * 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.
> -
> * If you get an "internal compiler error (ICE)" or test failures, see
> `below`.
>
> @@ -134,7 +159,8 @@ Windows x64 x86-64
> #. 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
> @@ -435,7 +461,7 @@ follows:
>
> * ``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
> @@ -664,66 +690,61 @@ Local LLVM Configuration
> ------------------------
>
> 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.
> +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, ARM, CppBackend, Hexagon,
> |
> +| | Mips, MSP430, NVPTX, PowerPC, R600, 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:
>
> @@ -733,47 +754,52 @@ 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
> +
> + These builds are the default. The build system will compile the tools
> and
> + libraries unoptimized, with debugging information, and asserts enabled.
> +
> +Release
> +
> + 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.
>
> -Debug Builds
> +RelWithDebInfo
>
> - 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``.
> -
> -Release (Optimized) Builds
> -
> - 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.
> -
> -Profile Builds
> -
> - 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.
> @@ -784,110 +810,51 @@ command:
>
> .. 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``
> +``make docs-llvm-html``
>
> - 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`` <http://llvm.org/docs>.
> -For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
> -``llvm.org/docs/SphinxQuickstartTemplate.html``
> <http://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
> @@ -908,44 +875,25 @@ This is accomplished in the typical auto
>
> % 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:
> + % cmake -G "Unix Makefiles" SRC_ROOT
>
> -Debug Builds with assertions enabled (the default)
> +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/Debug+Asserts/bin``
> -
> - Libraries
> -
> - ``OBJ_ROOT/Debug+Asserts/lib``
> -
> -Release Builds
> -
> - Tools
> -
> - ``OBJ_ROOT/Release/bin``
> -
> - Libraries
> -
> - ``OBJ_ROOT/Release/lib``
> -
> -Profile Builds
> -
> - Tools
> -
> - ``OBJ_ROOT/Profile/bin``
> -
> - Libraries
> -
> - ``OBJ_ROOT/Profile/lib``
> + .. code-block:: console
> +
> + % cd llvm_build_dir
> + % find lib/Support/ -name APFloat*
> + lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o
>
> Optional Configuration Items
> ----------------------------
>
> Modified: llvm/trunk/docs/index.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=232135&r1=232134&r2=232135&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/index.rst (original)
> +++ llvm/trunk/docs/index.rst Thu Mar 12 20:58:14 2015
> @@ -70,6 +70,7 @@ representation.
> CommandGuide/index
> GettingStarted
> GettingStartedVS
> + BuildingLLVMWithAutotools
> FAQ
> Lexicon
> HowToAddABuilder
> @@ -105,6 +106,10 @@ representation.
> An addendum to the main Getting Started guide for those using Visual
> Studio
> on Windows.
>
> +:doc:`BuildingLLVMWithAutotools`
> + An addendum to the Getting Started guide with instructions for
> building LLVM
> + with the Autotools build system.
> +
> :doc:`tutorial/index`
> Tutorials about using LLVM. Includes a tutorial about making a custom
> language with LLVM.
>
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150313/7e518ac2/attachment.html>
More information about the llvm-commits
mailing list