docs/BuildingLLVMWithAutotools.rst

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