docs/BuildingLLVMWithAutotools.rst

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