1 ====================================
2 Building LLVM With Autotools
3 ====================================
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>`_
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>`_.
24 #. Configure and build LLVM and Clang:
26 * ``cd where-you-want-to-build-llvm``
27 * ``mkdir build`` (for building without polluting the source dir)
29 * ``../llvm/configure [options]``
32 * ``--prefix=directory`` --- Specify for *directory* the full pathname of
33 where you want the LLVM tools and libraries to be installed (default
36 * ``--enable-optimized`` --- Compile with optimizations enabled (default
39 * ``--enable-assertions`` --- Compile with assertion checks enabled
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
47 * ``make check-all`` --- This run the regression tests to ensure everything
50 * If you get an "internal compiler error (ICE)" or test failures, see
51 `here <GettingStarted.html#check-here>`_.
53 Local LLVM Configuration
54 ------------------------
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.
62 The following environment variables are used by the ``configure`` script to
63 configure the build system:
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 |
78 +------------+-----------------------------------------------------------+
80 The following options can be used to set or enable LLVM specific options:
82 ``--enable-optimized``
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).
89 ``--enable-debug-runtime``
91 Enables debug symbols in the runtime libraries. The default is to strip debug
92 symbols from the runtime libraries.
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.
100 ``--enable-targets=target-option``
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:
108 ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
109 powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``.
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
118 To configure LLVM, follow these steps:
120 #. Change directory into the object root directory:
122 .. code-block:: console
126 #. Run the ``configure`` script located in the LLVM source tree:
128 .. code-block:: console
130 % $LLVM_SRC_DIR/configure --prefix=/install/path [other options]
132 Compiling the LLVM Suite Source Code
133 ------------------------------------
135 Once you have configured LLVM, you can build it. There are three types of
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``.
146 Release (Optimized) Builds
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.
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.
161 Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
162 directory and issuing the following command:
164 .. code-block:: console
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.
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
175 .. code-block:: console
179 There are several special targets which are useful when working with the LLVM
184 Removes all files generated by the build. This includes object files,
185 generated C/C++ files, libraries, and executables.
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.
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``.
199 ``gmake -C runtime install-bytecode``
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
206 Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
207 these ``make`` targets and descriptions of other targets available.
209 It is also possible to override default values from ``configure`` by declaring
210 variables on the command line. The following are some examples:
212 ``gmake ENABLE_OPTIMIZED=1``
214 Perform a Release (Optimized) build.
216 ``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
218 Perform a Release (Optimized) build without assertions enabled.
220 ``gmake ENABLE_OPTIMIZED=0``
222 Perform a Debug build.
224 ``gmake ENABLE_PROFILING=1``
226 Perform a Profiling build.
230 Print what ``gmake`` is doing on standard output.
232 ``gmake TOOL_VERBOSE=1``
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``.
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.
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
249 The generated documentation is built in the ``$LLVM_SRC_DIR/docs`` directory using
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:
257 .. code-block:: console
259 $ cd $LLVM_SRC_DIR/docs
260 $ make -f Makefile.sphinx
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.
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.
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).
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.
286 The Location of LLVM Object Files
287 ---------------------------------
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.
293 This is accomplished in the typical autoconf manner:
295 * Change directory to where the LLVM object files should live:
297 .. code-block:: console
301 * Run the ``configure`` script found in the LLVM source directory:
303 .. code-block:: console
305 % $LLVM_SRC_DIR/configure
307 The LLVM build will place files underneath *OBJ_ROOT* in directories named after
310 Debug Builds with assertions enabled (the default)
314 ``OBJ_ROOT/Debug+Asserts/bin``
318 ``OBJ_ROOT/Debug+Asserts/lib``
324 ``OBJ_ROOT/Release/bin``
328 ``OBJ_ROOT/Release/lib``
334 ``OBJ_ROOT/Profile/bin``
338 ``OBJ_ROOT/Profile/lib``