docs/BuildingLLVMWithAutotools.rst

   1 ====================================
   2 Building LLVM With Autotools
   3 ====================================
   4
   5 .. contents::
   6    :local:
   7
   8 Overview
   9 ========
  10
  11 This document details how to use the LLVM autotools based build system to
  12 configure and build LLVM from source. The normal developer process using CMake
  13 is detailed `here <GettingStarted.html#check-here>`_.
  14
  15 A Quick Summary
  16 ---------------
  17
  18 #. Configure and build LLVM and Clang:
  19
  20    * ``cd where-you-want-to-build-llvm``
  21    * ``mkdir build`` (for building without polluting the source dir)
  22    * ``cd build``
  23    * ``../llvm/configure [options]``
  24      Some common options:
  25
  26      * ``--prefix=directory`` --- Specify for *directory* the full pathname of
  27        where you want the LLVM tools and libraries to be installed (default
  28        ``/usr/local``).
  29
  30      * ``--enable-optimized`` --- Compile with optimizations enabled (default
  31        is NO).
  32
  33      * ``--enable-assertions`` --- Compile with assertion checks enabled
  34        (default is YES).
  35
  36    * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
  37      simultaneously.  This builds both LLVM and Clang for Debug+Asserts mode.
  38      The ``--enable-optimized`` configure option is used to specify a Release
  39      build.
  40
  41    * ``make check-all`` --- This run the regression tests to ensure everything
  42      is in working order.
  43
  44    * If you get an "internal compiler error (ICE)" or test failures, see
  45      `here <GettingStarted.html#check-here>`_.
  46
  47 Local LLVM Configuration
  48 ------------------------
  49
  50 Once checked out from the Subversion repository, the LLVM suite source code must
  51 be configured via the ``configure`` script.  This script sets variables in the
  52 various ``*.in`` files, most notably ``llvm/Makefile.config`` and
  53 ``llvm/include/Config/config.h``.  It also populates *OBJ_ROOT* with the
  54 Makefiles needed to begin building LLVM.
  55
  56 The following environment variables are used by the ``configure`` script to
  57 configure the build system:
  58
  59 +------------+-----------------------------------------------------------+
  60 | Variable   | Purpose                                                   |
  61 +============+===========================================================+
  62 | CC         | Tells ``configure`` which C compiler to use.  By default, |
  63 |            | ``configure`` will check ``PATH`` for ``clang`` and GCC C |
  64 |            | compilers (in this order).  Use this variable to override |
  65 |            | ``configure``\'s  default behavior.                       |
  66 +------------+-----------------------------------------------------------+
  67 | CXX        | Tells ``configure`` which C++ compiler to use.  By        |
  68 |            | default, ``configure`` will check ``PATH`` for            |
  69 |            | ``clang++`` and GCC C++ compilers (in this order).  Use   |
  70 |            | this variable to override  ``configure``'s default        |
  71 |            | behavior.                                                 |
  72 +------------+-----------------------------------------------------------+
  73
  74 The following options can be used to set or enable LLVM specific options:
  75
  76 ``--enable-optimized``
  77
  78   Enables optimized compilation (debugging symbols are removed and GCC
  79   optimization flags are enabled). Note that this is the default setting if you
  80   are using the LLVM distribution. The default behavior of a Subversion
  81   checkout is to use an unoptimized build (also known as a debug build).
  82
  83 ``--enable-debug-runtime``
  84
  85   Enables debug symbols in the runtime libraries. The default is to strip debug
  86   symbols from the runtime libraries.
  87
  88 ``--enable-jit``
  89
  90   Compile the Just In Time (JIT) compiler functionality.  This is not available
  91   on all platforms.  The default is dependent on platform, so it is best to
  92   explicitly enable it if you want it.
  93
  94 ``--enable-targets=target-option``
  95
  96   Controls which targets will be built and linked into llc. The default value
  97   for ``target_options`` is "all" which builds and links all available targets.
  98   The "host" target is selected as the target of the build host. You can also
  99   specify a comma separated list of target names that you want available in llc.
 100   The target names use all lower case. The current set of targets is:
 101
 102     ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
 103     powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``.
 104
 105 ``--enable-doxygen``
 106
 107   Look for the doxygen program and enable construction of doxygen based
 108   documentation from the source code. This is disabled by default because
 109   generating the documentation can take a long time and producess 100s of
 110   megabytes of output.
 111
 112 To configure LLVM, follow these steps:
 113
 114 #. Change directory into the object root directory:
 115
 116    .. code-block:: console
 117
 118      % cd OBJ_ROOT
 119
 120 #. Run the ``configure`` script located in the LLVM source tree:
 121
 122    .. code-block:: console
 123
 124      % $LLVM_SRC_DIR/configure --prefix=/install/path [other options]
 125
 126 Compiling the LLVM Suite Source Code
 127 ------------------------------------
 128
 129 Once you have configured LLVM, you can build it.  There are three types of
 130 builds:
 131
 132 Debug Builds
 133
 134   These builds are the default when one is using a Subversion checkout and
 135   types ``gmake`` (unless the ``--enable-optimized`` option was used during
 136   configuration).  The build system will compile the tools and libraries with
 137   debugging information.  To get a Debug Build using the LLVM distribution the
 138   ``--disable-optimized`` option must be passed to ``configure``.
 139
 140 Release (Optimized) Builds
 141
 142   These builds are enabled with the ``--enable-optimized`` option to
 143   ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command
 144   line.  For these builds, the build system will compile the tools and libraries
 145   with GCC optimizations enabled and strip debugging information from the
 146   libraries and executables it generates.  Note that Release Builds are default
 147   when using an LLVM distribution.
 148
 149 Profile Builds
 150
 151   These builds are for use with profiling.  They compile profiling information
 152   into the code for use with programs like ``gprof``.  Profile builds must be
 153   started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line.
 154
 155 Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
 156 directory and issuing the following command:
 157
 158 .. code-block:: console
 159
 160   % gmake
 161
 162 If the build fails, please `check here <GettingStarted.html#check-here>`_
 163 to see if you are using a version of GCC that is known not to compile LLVM.
 164
 165 If you have multiple processors in your machine, you may wish to use some of the
 166 parallel build options provided by GNU Make.  For example, you could use the
 167 command:
 168
 169 .. code-block:: console
 170
 171   % gmake -j2
 172
 173 There are several special targets which are useful when working with the LLVM
 174 source code:
 175
 176 ``gmake clean``
 177
 178   Removes all files generated by the build.  This includes object files,
 179   generated C/C++ files, libraries, and executables.
 180
 181 ``gmake dist-clean``
 182
 183   Removes everything that ``gmake clean`` does, but also removes files generated
 184   by ``configure``.  It attempts to return the source tree to the original state
 185   in which it was shipped.
 186
 187 ``gmake install``
 188
 189   Installs LLVM header files, libraries, tools, and documentation in a hierarchy
 190   under ``$PREFIX``, specified with ``$LLVM_SRC_DIR/configure --prefix=[dir]``, which
 191   defaults to ``/usr/local``.
 192
 193 ``gmake -C runtime install-bytecode``
 194
 195   Assuming you built LLVM into $OBJDIR, when this command is run, it will
 196   install bitcode libraries into the GCC front end's bitcode library directory.
 197   If you need to update your bitcode libraries, this is the target to use once
 198   you've built them.
 199
 200 Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
 201 these ``make`` targets and descriptions of other targets available.
 202
 203 It is also possible to override default values from ``configure`` by declaring
 204 variables on the command line.  The following are some examples:
 205
 206 ``gmake ENABLE_OPTIMIZED=1``
 207
 208   Perform a Release (Optimized) build.
 209
 210 ``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
 211
 212   Perform a Release (Optimized) build without assertions enabled.
 213
 214 ``gmake ENABLE_OPTIMIZED=0``
 215
 216   Perform a Debug build.
 217
 218 ``gmake ENABLE_PROFILING=1``
 219
 220   Perform a Profiling build.
 221
 222 ``gmake VERBOSE=1``
 223
 224   Print what ``gmake`` is doing on standard output.
 225
 226 ``gmake TOOL_VERBOSE=1``
 227
 228   Ask each tool invoked by the makefiles to print out what it is doing on
 229   the standard output. This also implies ``VERBOSE=1``.
 230
 231 Every directory in the LLVM object tree includes a ``Makefile`` to build it and
 232 any subdirectories that it contains.  Entering any directory inside the LLVM
 233 object tree and typing ``gmake`` should rebuild anything in or below that
 234 directory that is out of date.
 235
 236 This does not apply to building the documentation.
 237 LLVM's (non-Doxygen) documentation is produced with the
 238 `Sphinx <http://sphinx-doc.org/>`_ documentation generation system.
 239 There are some HTML documents that have not yet been converted to the new
 240 system (which uses the easy-to-read and easy-to-write
 241 `reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup
 242 language).
 243 The generated documentation is built in the ``$LLVM_SRC_DIR/docs`` directory using
 244 a special makefile.
 245 For instructions on how to install Sphinx, see
 246 `Sphinx Introduction for LLVM Developers
 247 <http://lld.llvm.org/sphinx_intro.html>`_.
 248 After following the instructions there for installing Sphinx, build the LLVM
 249 HTML documentation by doing the following:
 250
 251 .. code-block:: console
 252
 253   $ cd $LLVM_SRC_DIR/docs
 254   $ make -f Makefile.sphinx
 255
 256 This creates a ``_build/html`` sub-directory with all of the HTML files, not
 257 just the generated ones.
 258 This directory corresponds to ``llvm.org/docs``.
 259 For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
 260 ``llvm.org/docs/SphinxQuickstartTemplate.html``.
 261 The :doc:`SphinxQuickstartTemplate` is useful when creating a new document.
 262
 263 Cross-Compiling LLVM
 264 --------------------
 265
 266 It is possible to cross-compile LLVM itself. That is, you can create LLVM
 267 executables and libraries to be hosted on a platform different from the platform
 268 where they are built (a Canadian Cross build). To configure a cross-compile,
 269 supply the configure script with ``--build`` and ``--host`` options that are
 270 different. The values of these options must be legal target triples that your
 271 GCC compiler supports.
 272
 273 The result of such a build is executables that are not runnable on on the build
 274 host (--build option) but can be executed on the compile host (--host option).
 275
 276 Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
 277 <http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
 278 about cross-compiling.
 279
 280 The Location of LLVM Object Files
 281 ---------------------------------
 282
 283 The LLVM build system is capable of sharing a single LLVM source tree among
 284 several LLVM builds.  Hence, it is possible to build LLVM for several different
 285 platforms or configurations using the same source tree.
 286
 287 This is accomplished in the typical autoconf manner:
 288
 289 * Change directory to where the LLVM object files should live:
 290
 291   .. code-block:: console
 292
 293     % cd OBJ_ROOT
 294
 295 * Run the ``configure`` script found in the LLVM source directory:
 296
 297   .. code-block:: console
 298
 299     % $LLVM_SRC_DIR/configure
 300
 301 The LLVM build will place files underneath *OBJ_ROOT* in directories named after
 302 the build type:
 303
 304 Debug Builds with assertions enabled (the default)
 305
 306   Tools
 307
 308     ``OBJ_ROOT/Debug+Asserts/bin``
 309
 310   Libraries
 311
 312     ``OBJ_ROOT/Debug+Asserts/lib``
 313
 314 Release Builds
 315
 316   Tools
 317
 318     ``OBJ_ROOT/Release/bin``
 319
 320   Libraries
 321
 322     ``OBJ_ROOT/Release/lib``
 323
 324 Profile Builds
 325
 326   Tools
 327
 328     ``OBJ_ROOT/Profile/bin``
 329
 330   Libraries
 331
 332     ``OBJ_ROOT/Profile/lib``