1 ====================================
2 Building LLVM With Autotools
3 ====================================
12 Local LLVM Configuration
13 ------------------------
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.
21 The following environment variables are used by the ``configure`` script to
22 configure the build system:
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 |
37 +------------+-----------------------------------------------------------+
39 The following options can be used to set or enable LLVM specific options:
41 ``--enable-optimized``
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).
48 ``--enable-debug-runtime``
50 Enables debug symbols in the runtime libraries. The default is to strip debug
51 symbols from the runtime libraries.
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.
59 ``--enable-targets=target-option``
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:
67 ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
68 powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``.
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
77 To configure LLVM, follow these steps:
79 #. Change directory into the object root directory:
81 .. code-block:: console
85 #. Run the ``configure`` script located in the LLVM source tree:
87 .. code-block:: console
89 % SRC_ROOT/configure --prefix=/install/path [other options]
91 Compiling the LLVM Suite Source Code
92 ------------------------------------
94 Once you have configured LLVM, you can build it. There are three types of
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``.
105 Release (Optimized) Builds
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.
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.
120 Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
121 directory and issuing the following command:
123 .. code-block:: console
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.
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
134 .. code-block:: console
138 There are several special targets which are useful when working with the LLVM
143 Removes all files generated by the build. This includes object files,
144 generated C/C++ files, libraries, and executables.
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.
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``.
158 ``gmake -C runtime install-bytecode``
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
165 Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
166 these ``make`` targets and descriptions of other targets available.
168 It is also possible to override default values from ``configure`` by declaring
169 variables on the command line. The following are some examples:
171 ``gmake ENABLE_OPTIMIZED=1``
173 Perform a Release (Optimized) build.
175 ``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
177 Perform a Release (Optimized) build without assertions enabled.
179 ``gmake ENABLE_OPTIMIZED=0``
181 Perform a Debug build.
183 ``gmake ENABLE_PROFILING=1``
185 Perform a Profiling build.
189 Print what ``gmake`` is doing on standard output.
191 ``gmake TOOL_VERBOSE=1``
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``.
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.
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
208 The generated documentation is built in the ``SRC_ROOT/docs`` directory using
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:
216 .. code-block:: console
219 $ make -f Makefile.sphinx
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.
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.
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).
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.
245 The Location of LLVM Object Files
246 ---------------------------------
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.
252 This is accomplished in the typical autoconf manner:
254 * Change directory to where the LLVM object files should live:
256 .. code-block:: console
260 * Run the ``configure`` script found in the LLVM source directory:
262 .. code-block:: console
266 The LLVM build will place files underneath *OBJ_ROOT* in directories named after
269 Debug Builds with assertions enabled (the default)
273 ``OBJ_ROOT/Debug+Asserts/bin``
277 ``OBJ_ROOT/Debug+Asserts/lib``
283 ``OBJ_ROOT/Release/bin``
287 ``OBJ_ROOT/Release/lib``
293 ``OBJ_ROOT/Profile/bin``
297 ``OBJ_ROOT/Profile/lib``