| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| "http://www.w3.org/TR/html4/strict.dtd"> |
| <html> |
| <head> |
| <title>Building LLVM with CMake</title> |
| <link rel="stylesheet" href="llvm.css" type="text/css"> |
| </head> |
| |
| <div class="doc_title"> |
| Building LLVM with CMake |
| </div> |
| |
| <ul> |
| <li><a href="#intro">Introduction</a></li> |
| <li><a href="#quickstart">Quick start</a></li> |
| <li><a href="#usage">Basic CMake usage</a> |
| <li><a href="#options">Options and variables</a> |
| <ul> |
| <li><a href="#freccmake">Frequently-used CMake variables</a></li> |
| <li><a href="#llvmvars">LLVM-specific variables</a></li> |
| </ul></li> |
| <li><a href="#testing">Executing the test suite</a> |
| <li><a href="#cross">Cross compiling</a> |
| <li><a href="#embedding">Embedding LLVM in your project</a> |
| <li><a href="#specifics">Compiler/Platform specific topics</a> |
| <ul> |
| <li><a href="#msvc">Microsoft Visual C++</a></li> |
| </ul></li> |
| </ul> |
| |
| <div class="doc_author"> |
| <p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p> |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="intro">Introduction</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p><a href="http://www.cmake.org/">CMake</a> is a cross-platform |
| build-generator tool. CMake does not build the project, it generates |
| the files needed by your build tool (GNU make, Visual Studio, etc) for |
| building LLVM.</p> |
| |
| <p>If you are really anxious about getting a functional LLVM build, |
| go to the <a href="#quickstart">Quick start</a> section. If you |
| are a CMake novice, start on <a href="#usage">Basic CMake |
| usage</a> and then go back to the <a href="#quickstart">Quick |
| start</a> once you know what you are |
| doing. The <a href="#options">Options and variables</a> section |
| is a reference for customizing your build. If you already have |
| experience with CMake, this is the recommended starting point. |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="quickstart">Quick start</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p> We use here the command-line, non-interactive CMake interface </p> |
| |
| <ol> |
| |
| <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a> |
| and install CMake. Version 2.8 is the minimum required.</p> |
| |
| <li><p>Open a shell. Your development tools must be reachable from this |
| shell through the PATH environment variable.</p> |
| |
| <li><p>Create a directory for containing the build. It is not |
| supported to build LLVM on the source directory. cd to this |
| directory:</p> |
| <div class="doc_code"> |
| <p><tt>mkdir mybuilddir</tt></p> |
| <p><tt>cd mybuilddir</tt></p> |
| </div> |
| |
| <li><p>Execute this command on the shell |
| replacing <i>path/to/llvm/source/root</i> with the path to the |
| root of your LLVM source tree:</p> |
| <div class="doc_code"> |
| <p><tt>cmake path/to/llvm/source/root</tt></p> |
| </div> |
| |
| <p>CMake will detect your development environment, perform a |
| series of test and generate the files required for building |
| LLVM. CMake will use default values for all build |
| parameters. See the <a href="#options">Options and variables</a> |
| section for fine-tuning your build</p> |
| |
| <p>This can fail if CMake can't detect your toolset, or if it |
| thinks that the environment is not sane enough. On this case |
| make sure that the toolset that you intend to use is the only |
| one reachable from the shell and that the shell itself is the |
| correct one for you development environment. CMake will refuse |
| to build MinGW makefiles if you have a POSIX shell reachable |
| through the PATH environment variable, for instance. You can |
| force CMake to use a given build tool, see |
| the <a href="#usage">Usage</a> section.</p> |
| |
| </ol> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="usage">Basic CMake usage</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>This section explains basic aspects of CMake, mostly for |
| explaining those options which you may need on your day-to-day |
| usage.</p> |
| |
| <p>CMake comes with extensive documentation in the form of html |
| files and on the cmake executable itself. Execute <i>cmake |
| --help</i> for further help options.</p> |
| |
| <p>CMake requires to know for which build tool it shall generate |
| files (GNU make, Visual Studio, Xcode, etc). If not specified on |
| the command line, it tries to guess it based on you |
| environment. Once identified the build tool, CMake uses the |
| corresponding <i>Generator</i> for creating files for your build |
| tool. You can explicitly specify the generator with the command |
| line option <i>-G "Name of the generator"</i>. For knowing the |
| available generators on your platform, execute</p> |
| |
| <div class="doc_code"> |
| <p><tt>cmake --help</tt></p> |
| </div> |
| |
| <p>This will list the generator's names at the end of the help |
| text. Generator's names are case-sensitive. Example:</p> |
| |
| <div class="doc_code"> |
| <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p> |
| </div> |
| |
| <p>For a given development platform there can be more than one |
| adequate generator. If you use Visual Studio "NMake Makefiles" |
| is a generator you can use for building with NMake. By default, |
| CMake chooses the more specific generator supported by your |
| development environment. If you want an alternative generator, |
| you must tell this to CMake with the <i>-G</i> option.</p> |
| |
| <p>TODO: explain variables and cache. Move explanation here from |
| #options section.</p> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="options">Options and variables</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>Variables customize how the build will be generated. Options are |
| boolean variables, with possible values ON/OFF. Options and |
| variables are defined on the CMake command line like this:</p> |
| |
| <div class="doc_code"> |
| <p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p> |
| </div> |
| |
| <p>You can set a variable after the initial CMake invocation for |
| changing its value. You can also undefine a variable:</p> |
| |
| <div class="doc_code"> |
| <p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p> |
| </div> |
| |
| <p>Variables are stored on the CMake cache. This is a file |
| named <tt>CMakeCache.txt</tt> on the root of the build |
| directory. Do not hand-edit it.</p> |
| |
| <p>Variables are listed here appending its type after a colon. It is |
| correct to write the variable and the type on the CMake command |
| line:</p> |
| |
| <div class="doc_code"> |
| <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p> |
| </div> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <div class="doc_subsection"> |
| <a name="freccmake">Frequently-used CMake variables</a> |
| </div> |
| |
| <div class="doc_text"> |
| |
| <p>Here are listed some of the CMake variables that are used often, |
| along with a brief explanation and LLVM-specific notes. For full |
| documentation, check the CMake docs or execute <i>cmake |
| --help-variable VARIABLE_NAME</i>.</p> |
| |
| <dl> |
| <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt> |
| |
| <dd>Sets the build type for <i>make</i> based generators. Possible |
| values are Release, Debug, RelWithDebInfo and MinSizeRel. On |
| systems like Visual Studio the user sets the build type with the IDE |
| settings.</dd> |
| |
| <dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt> |
| <dd>Path where LLVM will be installed if "make install" is invoked |
| or the "INSTALL" target is built.</dd> |
| |
| <dt><b>LLVM_LIBDIR_SUFFIX</b>:STRING</dt> |
| <dd>Extra suffix to append to the directory where libraries are to |
| be installed. On a 64-bit architecture, one could use |
| -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.</dd> |
| |
| <dt><b>CMAKE_C_FLAGS</b>:STRING</dt> |
| <dd>Extra flags to use when compiling C source files.</dd> |
| |
| <dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt> |
| <dd>Extra flags to use when compiling C++ source files.</dd> |
| |
| <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt> |
| <dd>Flag indicating is shared libraries will be built. Its default |
| value is OFF. Shared libraries are not supported on Windows and |
| not recommended in the other OSes.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- ======================================================================= --> |
| <div class="doc_subsection"> |
| <a name="llvmvars">LLVM-specific variables</a> |
| </div> |
| |
| <div class="doc_text"> |
| |
| <dl> |
| <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt> |
| <dd>Semicolon-separated list of targets to build, or <i>all</i> for |
| building all targets. Case-sensitive. For Visual C++ defaults |
| to <i>X86</i>. On the other cases defaults to <i>all</i>. Example: |
| <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd> |
| |
| <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt> |
| <dd>Build LLVM tools. Defaults to ON. Targets for building each tool |
| are generated in any case. You can build an tool separately by |
| invoking its target. For example, you can build <i>llvm-as</i> |
| with a makefile-based system executing <i>make llvm-as</i> on the |
| root of your build directory.</dd> |
| |
| <dt><b>LLVM_INCLUDE_TOOLS</b>:BOOL</dt> |
| <dd>Generate build targets for the LLVM tools. Defaults to |
| ON. You can use that option for disabling the generation of build |
| targets for the LLVM tools.</dd> |
| |
| <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt> |
| <dd>Build LLVM examples. Defaults to OFF. Targets for building each |
| example are generated in any case. See documentation |
| for <i>LLVM_BUILD_TOOLS</i> above for more details.</dd> |
| |
| <dt><b>LLVM_INCLUDE_EXAMPLES</b>:BOOL</dt> |
| <dd>Generate build targets for the LLVM examples. Defaults to |
| ON. You can use that option for disabling the generation of build |
| targets for the LLVM examples.</dd> |
| |
| <dt><b>LLVM_BUILD_TESTS</b>:BOOL</dt> |
| <dd>Build LLVM unit tests. Defaults to OFF. Targets for building |
| each unit test are generated in any case. You can build a specific |
| unit test with the target <i>UnitTestNameTests</i> (where at this |
| time <i>UnitTestName</i> can be ADT, Analysis, ExecutionEngine, |
| JIT, Support, Transform, VMCore; see the subdirectories |
| of <i>unittests</i> for an updated list.) It is possible to build |
| all unit tests with the target <i>UnitTests</i>.</dd> |
| |
| <dt><b>LLVM_INCLUDE_TESTS</b>:BOOL</dt> |
| <dd>Generate build targets for the LLVM unit tests. Defaults to |
| ON. You can use that option for disabling the generation of build |
| targets for the LLVM unit tests.</dd> |
| |
| <dt><b>LLVM_APPEND_VC_REV</b>:BOOL</dt> |
| <dd>Append version control revision info (svn revision number or git |
| revision id) to LLVM version string (stored in the PACKAGE_VERSION |
| macro). For this to work cmake must be invoked before the |
| build. Defaults to OFF.</dd> |
| |
| <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt> |
| <dd>Build with threads support, if available. Defaults to ON.</dd> |
| |
| <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt> |
| <dd>Enables code assertions. Defaults to OFF if and only if |
| CMAKE_BUILD_TYPE is <i>Release</i>.</dd> |
| |
| <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt> |
| <dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the |
| compiler supports this flag. Some systems, like Windows, do not |
| need this flag. Defaults to ON.</dd> |
| |
| <dt><b>LLVM_ENABLE_WARNINGS</b>:BOOL</dt> |
| <dd>Enable all compiler warnings. Defaults to ON.</dd> |
| |
| <dt><b>LLVM_ENABLE_PEDANTIC</b>:BOOL</dt> |
| <dd>Enable pedantic mode. This disable compiler specific extensions, is |
| possible. Defaults to ON.</dd> |
| |
| <dt><b>LLVM_ENABLE_WERROR</b>:BOOL</dt> |
| <dd>Stop and fail build, if a compiler warning is |
| triggered. Defaults to OFF.</dd> |
| |
| <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt> |
| <dd>Build 32-bits executables and libraries on 64-bits systems. This |
| option is available only on some 64-bits unix systems. Defaults to |
| OFF.</dd> |
| |
| <dt><b>LLVM_TARGET_ARCH</b>:STRING</dt> |
| <dd>LLVM target to use for native code generation. This is required |
| for JIT generation. It defaults to "host", meaning that it shall |
| pick the architecture of the machine where LLVM is being built. If |
| you are cross-compiling, set it to the target architecture |
| name.</dd> |
| |
| <dt><b>LLVM_TABLEGEN</b>:STRING</dt> |
| <dd>Full path to a native TableGen executable (usually |
| named <i>tblgen</i>). This is intented for cross-compiling: if the |
| user sets this variable, no native TableGen will be created.</dd> |
| |
| <dt><b>LLVM_LIT_ARGS</b>:STRING</dt> |
| <dd>Arguments given to lit. |
| <tt>make check</tt> and <tt>make clang-test</tt> are affected. |
| By default, <tt>"-sv --no-progress-bar"</tt> |
| on Visual C++ and Xcode, |
| <tt>"-sv"</tt> on others.</dd> |
| |
| <dt><b>LLVM_LIT_TOOLS_DIR</b>:STRING</dt> |
| <dd>The path to GnuWin32 tools for tests. Valid on Windows host. |
| Defaults to "", then Lit seeks tools according to %PATH%. |
| Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first, |
| without specifying GnuWin32 to %PATH%.</dd> |
| |
| <dt><b>LLVM_ENABLE_FFI</b>:BOOL</dt> |
| <dd>Indicates whether LLVM Interpreter will be linked with Foreign |
| Function Interface library. If the library or its headers are |
| installed on a custom location, you can set the variables |
| FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. Defaults to OFF.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="testing">Executing the test suite</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>Testing is performed when the <i>check</i> target is built. For |
| instance, if you are using makefiles, execute this command while on |
| the top level of your build directory:</p> |
| |
| <div class="doc_code"> |
| <p><tt>make check</tt></p> |
| </div> |
| |
| <p>On Visual Studio, you may run tests to build the project "check".</p> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="cross">Cross compiling</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this |
| wiki page</a> for generic instructions on how to cross-compile |
| with CMake. It goes into detailed explanations and may seem |
| daunting, but it is not. On the wiki page there are several |
| examples including toolchain files. Go directly to |
| <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this |
| section</a> for a quick solution.</p> |
| |
| <p>Also see the <a href="#llvmvars">LLVM-specific variables</a> |
| section for variables used when cross-compiling.</p> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="embedding">Embedding LLVM in your project</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>The most difficult part of adding LLVM to the build of a project |
| is to determine the set of LLVM libraries corresponding to the set |
| of required LLVM features. What follows is an example of how to |
| obtain this information:</p> |
| |
| <div class="doc_code"> |
| <pre> |
| <b># A convenience variable:</b> |
| set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.") |
| <b># A bit of a sanity check:</b> |
| if( NOT EXISTS ${LLVM_ROOT}/include/llvm ) |
| message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install") |
| endif() |
| <b># We incorporate the CMake features provided by LLVM:</b> |
| set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake") |
| include(LLVM) |
| <b># Now set the header and library paths:</b> |
| include_directories( ${LLVM_ROOT}/include ) |
| link_directories( ${LLVM_ROOT}/lib ) |
| <b># Let's suppose we want to build a JIT compiler with support for |
| # binary code (no interpreter):</b> |
| llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) |
| <b># Finally, we link the LLVM libraries to our executable:</b> |
| target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) |
| </pre> |
| </div> |
| |
| <p>This assumes that LLVM_ROOT points to an install of LLVM. The |
| procedure works too for uninstalled builds although we need to take |
| care to add an <i>include_directories</i> for the location of the |
| headers on the LLVM source directory (if we are building |
| out-of-source.)</p> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| |
| <!-- *********************************************************************** --> |
| <div class="doc_section"> |
| <a name="specifics">Compiler/Platform specific topics</a> |
| </div> |
| <!-- *********************************************************************** --> |
| |
| <div class="doc_text"> |
| |
| <p>Notes for specific compilers and/or platforms.</p> |
| |
| </div> |
| |
| <div class="doc_subsection"> |
| <a name="msvc">Microsoft Visual C++</a> |
| </div> |
| |
| <div class="doc_text"> |
| |
| <dl> |
| <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt> |
| <dd>Specifies the maximum number of parallell compiler jobs to use |
| per project when building with msbuild or Visual Studio. Only supported for |
| Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all |
| processors. Default is 0.</dd> |
| </dl> |
| |
| </div> |
| |
| <!-- *********************************************************************** --> |
| |
| <hr> |
| <address> |
| <a href="http://jigsaw.w3.org/css-validator/check/referer"><img |
| src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> |
| <a href="http://validator.w3.org/check/referer"><img |
| src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> |
| |
| <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br> |
| <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> |
| Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $ |
| </address> |
| |
| </body> |
| </html> |