Updating GettingStarted documentation to reference CMake as the preferred way to build LLVM.

[samsonov]

docs/GettingStarted.rst

715

This variable is already mentioned above.

721

Probably, we should specifiy that this is a semicolon-separated list of strings.

722

s/equivolent/equivalent

730

s/nad/and

735

s/nad/and

876

I feel like example will be better.

$ cd llvm_build_dir
$ find lib/Support/ -name APFloat*
lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o

[chandlerc]

I'm happy for Alexey and others to review, I just wanted to say....

WOOOOOT!

[beanz]

Updates based on Alexey's feedback.

[mehdi_amini]

docs/GettingStarted.rst

718

s/TARGEST/TARGET/

729

s/soruce/source/

734

s/soruce/source/

875

s/cooresponding/corresponding/

[beanz]

Obviously I can't spell or type (spell check module installed).

[beanz]

• Adding documentation for LLVM_BUILD_LLVM_DYLIB
• Fixing a doc build issue

[beanz]

Addind documentation for LLVM_OPTIMIZED_TABLEGEN, which was just landed in r231842.

[samsonov]

docs/BuildingLLVMWithAutotools.rst

3

Update the page name?

298

Please fix

docs/GettingStarted.rst

73

make-compatible

76

Probably you should add "." or ";" at the end of bullets.

88

FTR existing LLVM CMake page uses ON/OFF instead of Yes/No

161–162

See above. Specify -DBUILD_SHARED_LIBS=ON?

698

"are passed to CMake"?

724

The order of sentences is weird. LLVM_ALL_TARGETS refers to all, and sentence about list format should be either at the very beginning, or at the end.

725

s/semi-colon/semicolon

729

I'd shorten it to "Build doxygen-based documentation from the source code. ..."

734

Ditto - I'd shorten it to "Build sphinx-based documentation from the source code. ..."

744

Do you really need to specify all the list items here? I'm pretty sure it will soon get out of date.

823–824

I think you need a comma before "this"

824

... generate a directory `OBJ_ROOT/docs/html` with HTML documentation.

837

"a Mac" -> "Mac OS X" ?

838

why not just "latest Xcode"?

[beanz]

Fixes based on feedback from samsonov.

[samsonov]

LGTM

[echristo]

No need to wait on me here, you've gotten other approvals.

Thanks!

-eric

docs/BuildingLLVMWithAutotools.rst

+====================================
+Getting Started with the LLVM System  
+====================================
+
+.. 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``.
+For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
+``llvm.org/docs/SphinxQuickstartTemplate.html``.
+The :doc:`SphinxQuickstartTemplate` is useful when creating a new document.
+
+Cross-Compiling LLVM
+--------------------
+
+It is possible to cross-compile LLVM itself. That is, you can create LLVM
+executables and libraries to be hosted on a platform different from the platform
+where they are 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``
 No newline at end of file

docs/GettingStarted.rst

#. Checkout Compiler-RT:
    * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
 
 #. Get the Test Suite Source Code **[Optional]**
 
    * ``cd where-you-want-llvm-to-live``
    * ``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):
+
+   * ``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=Yes`` --- Compile with assertion checks enabled
+       (default is Yes for Debug builds, No for all other build types).
+
+   * For more information see `CMake <CMake.html>`_
+
+#. Configure and build LLVM and Clang (Alternate process using configure):
 
    * ``cd where-you-want-to-build-llvm``
    * ``mkdir build`` (for building without polluting the source dir)
    * ``cd build``
    * ``../llvm/configure [options]``
      Some common options:
 
      * ``--prefix=directory`` --- Specify for *directory* the full pathname of
#. Configure and build LLVM and Clang (Alternate process using configure):
    * ``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.
 
    * ``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`.
 
 Consult the `Getting Started with LLVM`_ section for detailed information on
 configuring and compiling LLVM.  See `Setting Up Your Environment`_ for tips
 that simplify working with the Clang front end and LLVM tools.  Go to `Program
 Layout`_ to learn about the layout of the source code tree.
 

 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=Yes`` 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
 mode, depending on the system (it is so large because of all the debugging
 information and the fact that the libraries are statically linked into multiple
 tools).  If you do not need many of the tools and you are space-conscious, you
 can pass ``ONLY_TOOLS="tools you need"`` to make.  The Release build requires
 considerably less space.

 -----------------------------
 
 If you have access to our Subversion repository, you can get a fresh copy of the
 entire source code.  All you need to do is check it out from Subversion as
 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://[e-mail]/svn/llvm-project/llvm/trunk llvm``
+* Read-Write: ``svn co https://[e-mail]/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
 copies of documentation files.
 
 If you want to get a specific release (as opposed to the most recent revision),
 you can checkout it from the '``tags``' directory (instead of '``trunk``'). The
 following releases are located in the following subdirectories of the '``tags``'
.. code-block:: console
   % git svn rebase -l
 
 Please, refer to the Git-SVN manual (``man git-svn``) for more information.
 
 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:
+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 specified 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                                                   |
-+============+===========================================================+
-| 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.
++-----------------------+------------------------------------------------------+
+| 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_CXX_COMPILER    | Tells ``cmake`` which C++ compiler to use.  By       |
+|                       | default, this will be /usr/bin/c++.                  |
++-----------------------+------------------------------------------------------+
+| CMAKE_INSTALL_PREFIX  | Specifies the install directory to target when       |
+|                       | running the install action of the build files.       |
++-----------------------+------------------------------------------------------+
+| LLVM_TARGEST_TO_BUILD | Controls which targets will be built and linked into |
+|                       | llc. This is equivolent to the ``--enable-targets``  |
+|                       | option in the configure script. The default value is |
+|                       | ``all``, which includes: ``AArch64, ARM, CppBackend, |
+|                       | Hexagon, Mips, MSP430, NVPTX, PowerPC, R600, Sparc,  |
+|                       | SystemZ, X86, XCore``. That list is defined as       |
+|                       | ``LLVM_ALL_TARGETS``, and can be mutated to include  |
+|                       | out-of-tree targets.                                 |
++-----------------------+------------------------------------------------------+
+| LLVM_ENABLE_DOXYGEN   | Look for the doxygen program nad enable construction |
+|                       | of the doxygen-based documentation from the soruce   |
+|                       | code. This is disabled by default because it is slow |
+|                       | and generates a lot of output.                       |
++-----------------------+------------------------------------------------------+
+| LLVM_ENABLE_SPHINX    | Look for the sphinx program nad enable construction  |
+|                       | of the sphinx-based documentation from the soruce    |
+|                       | code. This is disabled by default because it is slow |
+|                       | and generates a lot 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:
+#. 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``.
-
-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 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.
+
+RelWithDebInfo
+
+  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.
 
 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
+  % 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.
+``make docs-llvm-html``
 
-``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 a Mac with
+a recent Xcode installation from the Mac App Store:
+
+.. code-block:: console
+
+  % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES=“armv7;armv7s;arm64"
+    -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake
+    -DLLVM_BUILD_TOOLS=No -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=No
+    -DLLVM_INCLUDE_UTILS=No -DLLVM_INCLUDE_TESTS=No -DLLVM_INCLUDE_EXAMPLES=No
+    -DLLVM_ENABLE_BACKTRACES=No [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
 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:
+* 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
-
-  Tools
-
-    ``OBJ_ROOT/Release/bin``
-
-  Libraries
-
-    ``OBJ_ROOT/Release/lib``
-
-Profile Builds
-
-  Tools
-
-    ``OBJ_ROOT/Profile/bin``
-
-  Libraries
+    % cmake -G "Unix Makefiles" SRC_ROOT
 
-    ``OBJ_ROOT/Profile/lib``
+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 cooresponding ``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.
 
 Optional Configuration Items
 ----------------------------
 
 If you're running on a Linux system that supports the `binfmt_misc
 <http://en.wikipedia.org/wiki/binfmt_misc>`_
 module, and you have root access on the system, you can set your system up to
 execute LLVM bitcode files directly. To do this, use commands like this (the

docs/index.rst

.. toctree::
    :hidden:
 
    CMake
    HowToBuildOnARM
    HowToCrossCompileLLVM
    CommandGuide/index
    GettingStarted
    GettingStartedVS
+   BuildingLLVMWithAutotools
    FAQ
    Lexicon
    HowToAddABuilder
    yaml2obj
    HowToSubmitABug
    SphinxQuickstartTemplate
    Phabricator
    TestingGuide

 
 :doc:`HowToCrossCompileLLVM`
    Notes on cross-building and testing LLVM/Clang.
 
 :doc:`GettingStartedVS`
    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.
 
 :doc:`LLVM Command Guide <CommandGuide/index>`
    A reference manual for the LLVM command line utilities ("man" pages for LLVM
    tools).