"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Building LLVM with CMake</title>
<link rel="stylesheet" href="llvm.css" type="text/css">
</head>
-<div class="doc_title">
+<h1>
Building LLVM with CMake
-</div>
+</h1>
<ul>
<li><a href="#intro">Introduction</a></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>
+ <ul>
+ <li><a href="#passdev">Developing LLVM pass out of source</a></li>
+ </ul></li>
<li><a href="#specifics">Compiler/Platform specific topics</a>
<ul>
<li><a href="#msvc">Microsoft Visual C++</a></li>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="intro">Introduction</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
build-generator tool. CMake does not build the project, it generates
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="quickstart">Quick start</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<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.6.2 is the minimum required.</p>
+ 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>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="usage">Basic CMake usage</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This section explains basic aspects of CMake, mostly for
explaining those options which you may need on your day-to-day
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>
+ <p><tt>cmake -G "Visual Studio 9 2008" path/to/llvm/source/root</tt></p>
</div>
<p>For a given development platform there can be more than one
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="options">Options and variables</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Variables customize how the build will be generated. Options are
boolean variables, with possible values ON/OFF. Options and
<p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
</div>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="freccmake">Frequently-used CMake variables</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Here are listed some of the CMake variables that are used often,
along with a brief explanation and LLVM-specific notes. For full
<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 MiniSizeRel. On
+ values are Release, Debug, RelWithDebInfo and MinSizeRel. On
systems like Visual Studio the user sets the build type with the IDE
settings.</dd>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="llvmvars">LLVM-specific variables</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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>
+ <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"</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 ON if and only if
+ <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 to the compiler command-line, if the
- compiler supports this flag. Some systems, like Windows, does not
- need this flag. Defaults to OFF.</dd>
+ <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>
+ option is available only on some 64-bits unix systems. Defaults to
+ OFF.</dd>
- <dt><b>LLVM_PLO_FLAGS</b>:STRING</dt>
- <dd>Extra flags for creating partially linked objects. Visual C++
- does not use this.</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>:PATH</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>
+
+ <dt><b>LLVM_CLANG_SOURCE_DIR</b>:PATH</dt>
+ <dd>Path to Clang's source directory. Defaults to tools/clang.
+ Clang will not be built when it is empty or it does not point valid
+ path.</dd>
+
+ <dt><b>LLVM_USE_OPROFILE</b>:BOOL</dt>
+ <dd> Enable building OProfile JIT support. Defaults to OFF</dd>
+
+ <dt><b>LLVM_USE_INTEL_JITEVENTS</b>:BOOL</dt>
+ <dd> Enable building support for Intel JIT Events API. Defaults to OFF</dd>
+
+ <dt><b>LLVM_INTEL_JITEVENTS_DIR</b>:PATH</dt>
+ <dd> Path to installation of Intel(R) VTune(TM) Amplifier XE 2011,
+ used to locate the <tt>jitprofiling</tt> library. Default =
+ <tt>%VTUNE_AMPLIFIER_XE_2011_DIR%</tt> (Windows)
+ | <tt>/opt/intel/vtune_amplifier_xe_2011</tt> (Linux) </dd>
+
</dl>
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="testing">Executing the test suite</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
-<p>LLVM testing is not supported on Visual Studio.</p>
+<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>TODO</p>
+<p>On Visual Studio, you may run tests to build the project "check".</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="cross">Cross compiling</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
wiki page</a> for generic instructions on how to cross-compile
<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">
+<h2>
<a name="embedding">Embedding LLVM in your project</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
-<p>TODO</p>
+ <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>
+ <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(LLVMConfig)
+ <b># Now set the header and library paths:</b>
+ include_directories( ${LLVM_INCLUDE_DIRS} )
+ link_directories( ${LLVM_LIBRARY_DIRS} )
+ add_definitions( ${LLVM_DEFINITIONS} )
+ <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>
+
+ <p>Alternativaly, you can utilize CMake's <i>find_package</i>
+ functionality. Here is an equivalent variant of snippet shown above:</p>
+
+ <div class="doc_code">
+ <pre>
+ find_package(LLVM)
+
+ if( NOT LLVM_FOUND )
+ message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
+ endif()
+
+ include_directories( ${LLVM_INCLUDE_DIRS} )
+ link_directories( ${LLVM_LIBRARY_DIRS} )
+ llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
+
+ target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
+ </pre>
+ </div>
+
+<!-- ======================================================================= -->
+<h3>
+ <a name="passdev">Developing LLVM pass out of source</a>
+</h3>
+
+<div>
+
+ <p>It is possible to develop LLVM passes against installed LLVM.
+ An example of project layout provided below:</p>
+
+ <div class="doc_code">
+ <pre>
+ <project dir>/
+ |
+ CMakeLists.txt
+ <pass name>/
+ |
+ CMakeLists.txt
+ Pass.cpp
+ ...
+ </pre>
+ </div>
+
+ <p>Contents of <project dir>/CMakeLists.txt:</p>
+
+ <div class="doc_code">
+ <pre>
+ find_package(LLVM)
+
+ <b># Define add_llvm_* macro's.</b>
+ include(AddLLVM)
+
+ add_definitions(${LLVM_DEFINITIONS})
+ include_directories(${LLVM_INCLUDE_DIRS})
+ link_directories(${LLVM_LIBRARY_DIRS})
+
+ add_subdirectory(<pass name>)
+ </pre>
+ </div>
+
+ <p>Contents of <project dir>/<pass name>/CMakeLists.txt:</p>
+
+ <div class="doc_code">
+ <pre>
+ add_llvm_loadable_module(LLVMPassname
+ Pass.cpp
+ )
+ </pre>
+ </div>
+
+ <p>When you are done developing your pass, you may wish to integrate it
+ into LLVM source tree. You can achieve it in two easy steps:<br>
+ 1. Copying <pass name> folder into <LLVM root>/lib/Transform directory.<br>
+ 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/lib/Transform/CMakeLists.txt</p>
+</div>
<!-- *********************************************************************** -->
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="specifics">Compiler/Platform specific topics</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Notes for specific compilers and/or platforms.</p>
+<h3>
+ <a name="msvc">Microsoft Visual C++</a>
+</h3>
+
+<div>
+
+<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>
+
</div>
<!-- *********************************************************************** -->
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: 2008-12-31 03:59:36 +0100 (Wed, 31 Dec 2008) $
+ <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>
projects / oota-llvm.git / blobdiff