diff options
Diffstat (limited to 'docs/GettingStarted.rst')
| -rw-r--r-- | docs/GettingStarted.rst | 377 |
1 files changed, 156 insertions, 221 deletions
diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst index fa55ece..18b3c1d 100644 --- a/docs/GettingStarted.rst +++ b/docs/GettingStarted.rst @@ -62,38 +62,50 @@ Here's the short story for getting up and running quickly with LLVM: * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite`` #. Configure and build LLVM and Clang: + + The usual build uses `CMake <CMake.html>`_. If you would rather use + autotools, see `Building LLVM with autotools <BuildingLLVMWithAutotools.html>`_. - * ``cd where-you-want-to-build-llvm`` - * ``mkdir build`` (for building without polluting the source dir) + * ``cd where you want to build llvm`` + * ``mkdir build`` * ``cd build`` - * ``../llvm/configure [options]`` - Some common options: + * ``cmake -G <generator> [options] <path to llvm sources>`` + + Some common generators are: - * ``--prefix=directory`` --- Specify for *directory* the full pathname of - where you want the LLVM tools and libraries to be installed (default - ``/usr/local``). + * ``Unix Makefiles`` --- for generating make-compatible parallel makefiles. + * ``Ninja`` --- for generating `Ninja <http://martine.github.io/ninja/>` + build files. + * ``Visual Studio`` --- for generating Visual Studio projects and + solutions. + * ``Xcode`` --- for generating Xcode projects. + + Some Common options: - * ``--enable-optimized`` --- Compile with optimizations enabled (default - is NO). + * ``-DCMAKE_INSTALL_PREFIX=directory`` --- Specify for *directory* the full + pathname of where you want the LLVM tools and libraries to be installed + (default ``/usr/local``). - * ``--enable-assertions`` --- Compile with assertion checks enabled - (default is YES). + * ``-DCMAKE_BUILD_TYPE=type`` --- Valid options for *type* are Debug, + Release, RelWithDebInfo, and MinSizeRel. Default is Debug. - * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run - simultaneously. This builds both LLVM and Clang for Debug+Asserts mode. - The ``--enable-optimized`` configure option is used to specify a Release - build. + * ``-DLLVM_ENABLE_ASSERTIONS=On`` --- Compile with assertion checks enabled + (default is Yes for Debug builds, No for all other build types). - * ``make check-all`` --- This run the regression tests to ensure everything - is in working order. + * Run your build tool of choice! - * It is also possible to use `CMake <CMake.html>`_ instead of the makefiles. - With CMake it is possible to generate project files for several IDEs: - Xcode, Eclipse CDT4, CodeBlocks, Qt-Creator (use the CodeBlocks - generator), KDevelop3. + * The default target (i.e. ``make``) will build all of LLVM + + * The ``check-all`` target (i.e. ``make check-all``) will run the + regression tests to ensure everything is in working order. + + * CMake will generate build targets for each tool and library, and most + LLVM sub-projects generate their own ``check-<project>`` target. + + * For more information see `CMake <CMake.html>`_ * If you get an "internal compiler error (ICE)" or test failures, see - `below`. + `below`_. Consult the `Getting Started with LLVM`_ section for detailed information on configuring and compiling LLVM. See `Setting Up Your Environment`_ for tips @@ -134,7 +146,8 @@ Windows x64 x86-64 Visual Studio #. Code generation supported for Pentium processors and up #. Code generation supported for 32-bit ABI only #. To use LLVM modules on Win32-based system, you may configure LLVM - with ``--enable-shared``. + with ``-DBUILD_SHARED_LIBS=On`` for CMake builds or ``--enable-shared`` + for configure builds. #. MCJIT not working well pre-v7, old JIT engine not supported any more. Note that you will need about 1-3 GB of space for a full LLVM build in Debug @@ -435,7 +448,7 @@ follows: * ``cd where-you-want-llvm-to-live`` * Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm`` -* Read-Write:``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` +* Read-Write: ``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm`` This will create an '``llvm``' directory in the current directory and fully populate it with the LLVM source code, Makefiles, test directories, and local @@ -664,66 +677,61 @@ Local LLVM Configuration ------------------------ Once checked out from the Subversion repository, the LLVM suite source code must -be configured via the ``configure`` script. This script sets variables in the -various ``*.in`` files, most notably ``llvm/Makefile.config`` and -``llvm/include/Config/config.h``. It also populates *OBJ_ROOT* with the -Makefiles needed to begin building LLVM. - -The following environment variables are used by the ``configure`` script to -configure the build system: - -+------------+-----------------------------------------------------------+ -| Variable | Purpose | -+============+===========================================================+ -| CC | Tells ``configure`` which C compiler to use. By default, | -| | ``configure`` will check ``PATH`` for ``clang`` and GCC C | -| | compilers (in this order). Use this variable to override | -| | ``configure``\'s default behavior. | -+------------+-----------------------------------------------------------+ -| CXX | Tells ``configure`` which C++ compiler to use. By | -| | default, ``configure`` will check ``PATH`` for | -| | ``clang++`` and GCC C++ compilers (in this order). Use | -| | this variable to override ``configure``'s default | -| | behavior. | -+------------+-----------------------------------------------------------+ - -The following options can be used to set or enable LLVM specific options: - -``--enable-optimized`` - - Enables optimized compilation (debugging symbols are removed and GCC - optimization flags are enabled). Note that this is the default setting if you - are using the LLVM distribution. The default behavior of a Subversion - checkout is to use an unoptimized build (also known as a debug build). - -``--enable-debug-runtime`` - - Enables debug symbols in the runtime libraries. The default is to strip debug - symbols from the runtime libraries. - -``--enable-jit`` - - Compile the Just In Time (JIT) compiler functionality. This is not available - on all platforms. The default is dependent on platform, so it is best to - explicitly enable it if you want it. - -``--enable-targets=target-option`` - - Controls which targets will be built and linked into llc. The default value - for ``target_options`` is "all" which builds and links all available targets. - The "host" target is selected as the target of the build host. You can also - specify a comma separated list of target names that you want available in llc. - The target names use all lower case. The current set of targets is: - - ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430, - powerpc, nvptx, r600, sparc, systemz, x86, x86_64, xcore``. - -``--enable-doxygen`` - - Look for the doxygen program and enable construction of doxygen based - documentation from the source code. This is disabled by default because - generating the documentation can take a long time and producess 100s of - megabytes of output. +be configured before being built. For instructions using autotools please see +`Building LLVM With Autotools <BuildingLLVMWithAutotools.html>`_. The +recommended process uses CMake. Unlinke the normal ``configure`` script, CMake +generates the build files in whatever format you request as well as various +``*.inc`` files, and ``llvm/include/Config/config.h``. + +Variables are passed to ``cmake`` on the command line using the format +``-D<variable name>=<value>``. The following variables are some common options +used by people developing LLVM. + ++-------------------------+----------------------------------------------------+ +| Variable | Purpose | ++=========================+====================================================+ +| CMAKE_C_COMPILER | Tells ``cmake`` which C compiler to use. By | +| | default, this will be /usr/bin/cc. | ++-------------------------+----------------------------------------------------+ +| CMAKE_CXX_COMPILER | Tells ``cmake`` which C++ compiler to use. By | +| | default, this will be /usr/bin/c++. | ++-------------------------+----------------------------------------------------+ +| CMAKE_BUILD_TYPE | Tells ``cmake`` what type of build you are trying | +| | to generate files for. Valid options are Debug, | +| | Release, RelWithDebInfo, and MinSizeRel. Default | +| | is Debug. | ++-------------------------+----------------------------------------------------+ +| CMAKE_INSTALL_PREFIX | Specifies the install directory to target when | +| | running the install action of the build files. | ++-------------------------+----------------------------------------------------+ +| LLVM_TARGETS_TO_BUILD | A semicolon delimited list controlling which | +| | targets will be built and linked into llc. This is | +| | equivalent to the ``--enable-targets`` option in | +| | the configure script. The default list is defined | +| | as ``LLVM_ALL_TARGETS``, and can be set to include | +| | out-of-tree targets. The default value includes: | +| | ``AArch64, ARM, CppBackend, Hexagon, | +| | Mips, MSP430, NVPTX, PowerPC, R600, Sparc, | +| | SystemZ, X86, XCore``. | ++-------------------------+----------------------------------------------------+ +| LLVM_ENABLE_DOXYGEN | Build doxygen-based documentation from the source | +| | code This is disabled by default because it is | +| | slow and generates a lot of output. | ++-------------------------+----------------------------------------------------+ +| LLVM_ENABLE_SPHINX | Build sphinx-based documentation from the source | +| | code. This is disabled by default because it is | +| | slow and generates a lot of output. | ++-------------------------+----------------------------------------------------+ +| LLVM_BUILD_LLVM_DYLIB | Generate libLLVM.so. This library contains a | +| | default set of LLVM components that can be | +| | overridden with ``LLVM_DYLIB_COMPONENTS``. The | +| | default contains most of LLVM and is defined in | +| | ``tools/llvm-shlib/CMakelists.txt``. | ++-------------------------+----------------------------------------------------+ +| LLVM_OPTIMIZED_TABLEGEN | Builds a release tablegen that gets used during | +| | the LLVM build. This can dramatically speed up | +| | debug builds. | ++-------------------------+----------------------------------------------------+ To configure LLVM, follow these steps: @@ -733,47 +741,52 @@ To configure LLVM, follow these steps: % cd OBJ_ROOT -#. Run the ``configure`` script located in the LLVM source tree: +#. Run the ``cmake``: .. code-block:: console - % SRC_ROOT/configure --prefix=/install/path [other options] + % cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX=prefix=/install/path + [other options] SRC_ROOT Compiling the LLVM Suite Source Code ------------------------------------ -Once you have configured LLVM, you can build it. There are three types of -builds: +Unlike with autotools, with CMake your build type is defined at configuration. +If you want to change your build type, you can re-run cmake with the following +invocation: + + .. code-block:: console + + % cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=type SRC_ROOT -Debug Builds +Between runs, CMake preserves the values set for all options. CMake has the +following build types defined: - These builds are the default when one is using a Subversion checkout and - types ``gmake`` (unless the ``--enable-optimized`` option was used during - configuration). The build system will compile the tools and libraries with - debugging information. To get a Debug Build using the LLVM distribution the - ``--disable-optimized`` option must be passed to ``configure``. +Debug -Release (Optimized) Builds + These builds are the default. The build system will compile the tools and + libraries unoptimized, with debugging information, and asserts enabled. - These builds are enabled with the ``--enable-optimized`` option to - ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command - line. For these builds, the build system will compile the tools and libraries - with GCC optimizations enabled and strip debugging information from the - libraries and executables it generates. Note that Release Builds are default - when using an LLVM distribution. +Release -Profile Builds + For these builds, the build system will compile the tools and libraries + with optimizations enabled and not generate debug info. CMakes default + optimization level is -O3. This can be configured by setting the + ``CMAKE_CXX_FLAGS_RELEASE`` variable on the CMake command line. - These builds are for use with profiling. They compile profiling information - into the code for use with programs like ``gprof``. Profile builds must be - started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line. +RelWithDebInfo + + These builds are useful when debugging. They generate optimized binaries with + debug information. CMakes default optimization level is -O2. This can be + configured by setting the ``CMAKE_CXX_FLAGS_RELWITHDEBINFO`` variable on the + CMake command line. Once you have LLVM configured, you can build it by entering the *OBJ_ROOT* directory and issuing the following command: .. code-block:: console - % gmake + % make If the build fails, please `check here`_ to see if you are using a version of GCC that is known not to compile LLVM. @@ -784,110 +797,51 @@ command: .. code-block:: console - % gmake -j2 + % make -j2 There are several special targets which are useful when working with the LLVM source code: -``gmake clean`` +``make clean`` Removes all files generated by the build. This includes object files, generated C/C++ files, libraries, and executables. -``gmake dist-clean`` - - Removes everything that ``gmake clean`` does, but also removes files generated - by ``configure``. It attempts to return the source tree to the original state - in which it was shipped. - -``gmake install`` +``make install`` Installs LLVM header files, libraries, tools, and documentation in a hierarchy - under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, which + under ``$PREFIX``, specified with ``CMAKE_INSTALL_PREFIX``, which defaults to ``/usr/local``. -``gmake -C runtime install-bytecode`` - - Assuming you built LLVM into $OBJDIR, when this command is run, it will - install bitcode libraries into the GCC front end's bitcode library directory. - If you need to update your bitcode libraries, this is the target to use once - you've built them. - -Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on -these ``make`` targets and descriptions of other targets available. - -It is also possible to override default values from ``configure`` by declaring -variables on the command line. The following are some examples: - -``gmake ENABLE_OPTIMIZED=1`` - - Perform a Release (Optimized) build. - -``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` - - Perform a Release (Optimized) build without assertions enabled. - -``gmake ENABLE_OPTIMIZED=0`` - - Perform a Debug build. - -``gmake ENABLE_PROFILING=1`` - - Perform a Profiling build. - -``gmake VERBOSE=1`` - - Print what ``gmake`` is doing on standard output. - -``gmake TOOL_VERBOSE=1`` - - Ask each tool invoked by the makefiles to print out what it is doing on - the standard output. This also implies ``VERBOSE=1``. - -Every directory in the LLVM object tree includes a ``Makefile`` to build it and -any subdirectories that it contains. Entering any directory inside the LLVM -object tree and typing ``gmake`` should rebuild anything in or below that -directory that is out of date. +``make docs-llvm-html`` -This does not apply to building the documentation. -LLVM's (non-Doxygen) documentation is produced with the -`Sphinx <http://sphinx-doc.org/>`_ documentation generation system. -There are some HTML documents that have not yet been converted to the new -system (which uses the easy-to-read and easy-to-write -`reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup -language). -The generated documentation is built in the ``SRC_ROOT/docs`` directory using -a special makefile. -For instructions on how to install Sphinx, see -`Sphinx Introduction for LLVM Developers -<http://lld.llvm.org/sphinx_intro.html>`_. -After following the instructions there for installing Sphinx, build the LLVM -HTML documentation by doing the following: - -.. code-block:: console - - $ cd SRC_ROOT/docs - $ make -f Makefile.sphinx - -This creates a ``_build/html`` sub-directory with all of the HTML files, not -just the generated ones. -This directory corresponds to ``llvm.org/docs``. -For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to -``llvm.org/docs/SphinxQuickstartTemplate.html``. -The :doc:`SphinxQuickstartTemplate` is useful when creating a new document. + If configured with ``-DLLVM_ENABLE_SPHINX=On``, this will generate a directory + at ``OBJ_ROOT/docs/html`` which contains the HTML formatted documentation. Cross-Compiling LLVM -------------------- It is possible to cross-compile LLVM itself. That is, you can create LLVM executables and libraries to be hosted on a platform different from the platform -where they are built (a Canadian Cross build). To configure a cross-compile, -supply the configure script with ``--build`` and ``--host`` options that are -different. The values of these options must be legal target triples that your -GCC compiler supports. +where they are built (a Canadian Cross build). To generate build files for +cross-compiling CMake provides a variable ``CMAKE_TOOLCHAIN_FILE`` which can +define compiler flags and variables used during the CMake test operations. The result of such a build is executables that are not runnable on on the build -host (--build option) but can be executed on the compile host (--host option). +host but can be executed on the target. As an example the following CMake +invocation can generate build files targeting iOS. This will work on Mac OS X +with the latest Xcode: + +.. code-block:: console + + % cmake -G "Ninja" -DCMAKE_OSX_ARCHITECTURES=“armv7;armv7s;arm64" + -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_LLVM>/cmake/platforms/iOS.cmake + -DCMAKE_BUILD_TYPE=Release -DLLVM_BUILD_RUNTIME=Off -DLLVM_INCLUDE_TESTS=Off + -DLLVM_INCLUDE_EXAMPLES=Off -DLLVM_ENABLE_BACKTRACES=Off [options] + <PATH_TO_LLVM> + +Note: There are some additional flags that need to be passed when building for +iOS due to limitations in the iOS SDK. Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general <http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information @@ -908,44 +862,25 @@ This is accomplished in the typical autoconf manner: % cd OBJ_ROOT -* Run the ``configure`` script found in the LLVM source directory: +* Run ``cmake``: .. code-block:: console - % SRC_ROOT/configure + % cmake -G "Unix Makefiles" SRC_ROOT -The LLVM build will place files underneath *OBJ_ROOT* in directories named after -the build type: +The LLVM build will create a structure underneath *OBJ_ROOT* that matches the +LLVM source tree. At each level where source files are present in the source +tree there will be a corresponding ``CMakeFiles`` directory in the *OBJ_ROOT*. +Underneath that directory there is another directory with a name ending in +``.dir`` under which you'll find object files for each source. -Debug Builds with assertions enabled (the default) +For example: - Tools - - ``OBJ_ROOT/Debug+Asserts/bin`` - - Libraries - - ``OBJ_ROOT/Debug+Asserts/lib`` - -Release Builds - - Tools - - ``OBJ_ROOT/Release/bin`` - - Libraries - - ``OBJ_ROOT/Release/lib`` - -Profile Builds - - Tools - - ``OBJ_ROOT/Profile/bin`` - - Libraries - - ``OBJ_ROOT/Profile/lib`` + .. code-block:: console + + % cd llvm_build_dir + % find lib/Support/ -name APFloat* + lib/Support/CMakeFiles/LLVMSupport.dir/APFloat.cpp.o Optional Configuration Items ---------------------------- |