mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-23 11:13:28 +01:00
453 lines
17 KiB
HTML
453 lines
17 KiB
HTML
<!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_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>
|
|
</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>Testing is not supported on Visual Studio.</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>
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
<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>
|