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`` 339
