1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
5 <title>Building LLVM with CMake</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
9 <div class="doc_title">
10 Building LLVM with CMake
14 <li><a href="#intro">Introduction</a></li>
15 <li><a href="#quickstart">Quick start</a></li>
16 <li><a href="#usage">Basic CMake usage</a>
17 <li><a href="#options">Options and variables</a>
19 <li><a href="#freccmake">Frequently-used CMake variables</a></li>
20 <li><a href="#llvmvars">LLVM-specific variables</a></li>
22 <li><a href="#testing">Executing the test suite</a>
23 <li><a href="#cross">Cross compiling</a>
24 <li><a href="#embedding">Embedding LLVM in your project</a>
27 <div class="doc_author">
28 <p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p>
31 <!-- *********************************************************************** -->
32 <div class="doc_section">
33 <a name="intro">Introduction</a>
35 <!-- *********************************************************************** -->
37 <div class="doc_text">
39 <p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
40 build-generator tool. CMake does not build the project, it generates
41 the files needed by your build tool (GNU make, Visual Studio, etc) for
44 <p>If you are really anxious about getting a functional LLVM build,
45 go to the <a href="#quickstart">Quick start</a> section. If you
46 are a CMake novice, start on <a href="#usage">Basic CMake
47 usage</a> and then go back to the <a href="#quickstart">Quick
48 start</a> once you know what you are
49 doing. The <a href="#options">Options and variables</a> section
50 is a reference for customizing your build. If you already have
51 experience with CMake, this is the recommended starting point.
54 <!-- *********************************************************************** -->
55 <div class="doc_section">
56 <a name="quickstart">Quick start</a>
58 <!-- *********************************************************************** -->
60 <div class="doc_text">
62 <p> We use here the command-line, non-interactive CMake interface </p>
66 <li><p><a href=http://www.cmake.org/cmake/resources/software.html>Download</a>
67 and install CMake. Version 2.6.2 is the minimum required.</p>
69 <li><p>Open a shell. Your development tools must be reachable from this
70 shell through the PATH environment variable.</p>
72 <li><p>Create a directory for containing the build. It is not
73 supported to build LLVM on the source directory. cd to this
75 <div class="doc_code">
76 <p><tt>mkdir mybuilddir</tt></p>
77 <p><tt>cd mybuilddir</tt></p>
80 <li><p>Execute this command on the shell
81 replacing <i>path/to/llvm/source/root</i> with the path to the
82 root of your LLVM source tree:</p>
83 <div class="doc_code">
84 <p><tt>cmake path/to/llvm/source/root</tt></p>
87 <p>CMake will detect your development environment, perform a
88 series of test and generate the files required for building
89 LLVM. CMake will use default values for all build
90 parameters. See the <a href="#options">Options and variables</a>
91 section for fine-tuning your build</p>
93 <p>This can fail if CMake can't detect your toolset, or if it
94 thinks that the environment is not sane enough. On this case
95 make sure that the toolset that you intend to use is the only
96 one reachable from the shell and that the shell itself is the
97 correct one for you development environment. CMake will refuse
98 to build MinGW makefiles if you have a POSIX shell reachable
99 through the PATH environment variable, for instance. You can
100 force CMake to use a given build tool, see
101 the <a href="#usage">Usage</a> section.</p>
107 <!-- *********************************************************************** -->
108 <div class="doc_section">
109 <a name="usage">Basic CMake usage</a>
111 <!-- *********************************************************************** -->
113 <div class="doc_text">
115 <p>This section explains basic aspects of CMake, mostly for
116 explaining those options which you may need on your day-to-day
119 <p>CMake comes with extensive documentation in the form of html
120 files and on the cmake executable itself. Execute <i>cmake
121 --help</i> for further help options.</p>
123 <p>CMake requires to know for which build tool it shall generate
124 files (GNU make, Visual Studio, Xcode, etc). If not specified on
125 the command line, it tries to guess it based on you
126 environment. Once identified the build tool, CMake uses the
127 corresponding <i>Generator</i> for creating files for your build
128 tool. You can explicitly specify the generator with the command
129 line option <i>-G "Name of the generator"</i>. For knowing the
130 available generators on your platform, execute</p>
132 <div class="doc_code">
133 <p><tt>cmake --help</tt></p>
136 <p>This will list the generator's names at the end of the help
137 text. Generator's names are case-sensitive. Example:</p>
139 <div class="doc_code">
140 <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p>
143 <p>For a given development platform there can be more than one
144 adequate generator. If you use Visual Studio "NMake Makefiles"
145 is a generator you can use for building with NMake. By default,
146 CMake chooses the more specific generator supported by your
147 development environment. If you want an alternative generator,
148 you must tell this to CMake with the <i>-G</i> option.</p>
150 <p>TODO: explain variables and cache. Move explanation here from
151 #options section.</p>
155 <!-- *********************************************************************** -->
156 <div class="doc_section">
157 <a name="options">Options and variables</a>
159 <!-- *********************************************************************** -->
161 <div class="doc_text">
163 <p>Variables customize how the build will be generated. Options are
164 boolean variables, with possible values ON/OFF. Options and
165 variables are defined on the CMake command line like this:</p>
167 <div class="doc_code">
168 <p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p>
171 <p>You can set a variable after the initial CMake invocation for
172 changing its value. You can also undefine a variable:</p>
174 <div class="doc_code">
175 <p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p>
178 <p>Variables are stored on the CMake cache. This is a file
179 named <it>CMakeCache.txt</it> on the root of the build
180 directory. Do not hand-edit it.</p>
182 <p>Variables are listed here appending its type after a colon. It is
183 correct to write the variable and the type on the CMake command
186 <div class="doc_code">
187 <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
192 <!-- ======================================================================= -->
193 <div class="doc_subsection">
194 <a name="freccmake">Frequently-used CMake variables</a>
197 <div class="doc_text">
199 <p>Here are listed some of the CMake variables that are used often,
200 along with a brief explanation and LLVM-specific notes. For full
201 documentation, check the CMake docs or execute <i>cmake
202 --help-variable VARIABLE_NAME</i>.
205 <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
207 <dd>Sets the build type for <i>make</i> based generators. Possible
208 values are Release, Debug, RelWithDebInfo and MiniSizeRel. On
209 systems like Visual Studio the user sets the build type with the IDE
212 <dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt>
213 <dd>Path where LLVM will be installed if "make install" is invoked
214 or the "INSTALL" target is built.</dd>
216 <dt><b>CMAKE_C_FLAGS</b>:STRING</dt>
217 <dd>Extra flags to use when compiling C source files.</dd>
219 <dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt>
220 <dd>Extra flags to use when compiling C++ source files.</dd>
222 <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
223 <dd>Flag indicating is shared libraries will be built. Its default
224 value is OFF. Shared libraries are not supported on Windows and
225 not recommended in the other OSes.</dd>
230 <!-- ======================================================================= -->
231 <div class="doc_subsection">
232 <a name="llvmvars">LLVM-specific variables</a>
235 <div class="doc_text">
238 <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
239 <dd>Semicolon-separated list of targets to build, or <i>all</i> for
240 building all targets. Case-sensitive. For Visual C++ defaults
241 to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
242 <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd>
244 <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
245 <dd>Build with threads support, if available. Defaults to ON.</dd>
247 <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
248 <dd>Add the <i>-fPIC</i> flag to the compiler command-line, if the
249 compiler supports this flag. Some systems, like Windows, does not
250 need this flag. Defaults to OFF.</dd>
252 <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
253 <dd>Build 32-bits executables and libraries on 64-bits systems. This
254 option is available only on some 64-bits unix systems. Defaults to
257 <dt><b>LLVM_PLO_FLAGS</b>:STRING</dt>
258 <dd>Extra flags for creating partially linked objects. Visual C++
259 does not use this.</dd>
261 <dt><b>LLVM_TABLEGEN</b>:STRING</dt>
262 <dd>Full path to a native TableGen executable (usually
263 named <i>tblgen</i>). This is intented for cross-compiling: if the
264 user sets this variable, no native TableGen will be created.</dd>
269 <!-- *********************************************************************** -->
270 <div class="doc_section">
271 <a name="testing">Executing the test suite</a>
273 <!-- *********************************************************************** -->
275 <div class="doc_text">
277 <p>LLVM testing is not supported on Visual Studio.</p>
283 <!-- *********************************************************************** -->
284 <div class="doc_section">
285 <a name="cross">Cross compiling</a>
287 <!-- *********************************************************************** -->
289 <div class="doc_text">
295 <!-- *********************************************************************** -->
296 <div class="doc_section">
297 <a name="embedding">Embedding LLVM in your project</a>
299 <!-- *********************************************************************** -->
301 <div class="doc_text">
307 <!-- *********************************************************************** -->
311 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
312 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
313 <a href="http://validator.w3.org/check/referer"><img
314 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
316 <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
317 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
318 Last modified: $Date: 2008-10-27 00:59:36 +0100 (Mon, 27 Oct 2008) $