Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 50843c0741d242ab59e10ef88ebfbb88ce8f63ba / . / docs / CMake.html
blob: f6ea6668063be7dc197109f091482d713337eaa3 [file] [log] [blame]
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>Building LLVM with CMake</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8
9<div class="doc_title">
10 Building LLVM with CMake
11</div>
12
13<ul>
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>
18 <ul>
19 <li><a href="#freccmake">Frequently-used CMake variables</a></li>
20 <li><a href="#llvmvars">LLVM-specific variables</a></li>
21 </ul></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>
25</ul>
26
27<div class="doc_author">
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]28<p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]29</div>
30
31<!-- *********************************************************************** -->
32<div class="doc_section">
33<a name="intro">Introduction</a>
34</div>
35<!-- *********************************************************************** -->
36
37<div class="doc_text">
38
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
42 building LLVM.</p>
43
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]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.
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]52</div>
53
54<!-- *********************************************************************** -->
55<div class="doc_section">
56<a name="quickstart">Quick start</a>
57</div>
58<!-- *********************************************************************** -->
59
60<div class="doc_text">
61
62<p> We use here the command-line, non-interactive CMake interface </p>
63
64<ol>
65
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>
68
69 <li><p>Open a shell. Your development tools must be reachable from this
70 shell through the PATH environment variable.</p>
71
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
74 directory:</p>
75 <div class="doc_code">
76 <p><tt>mkdir mybuilddir</tt></p>
77 <p><tt>cd mybuilddir</tt></p>
78 </div>
79
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>
85 </div>
86
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>
92
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>
102
103</ol>
104
105</div>
106
107<!-- *********************************************************************** -->
108<div class="doc_section">
109 <a name="usage">Basic CMake usage</a>
110</div>
111<!-- *********************************************************************** -->
112
113<div class="doc_text">
114
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]115 <p>This section explains basic aspects of CMake, mostly for
116 explaining those options which you may need on your day-to-day
117 usage.</p>
118
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>
122
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>
131
132 <div class="doc_code">
133 <p><tt>cmake --help</tt></p>
134 </div>
135
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>
138
139 <div class="doc_code">
140 <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p>
141 </div>
142
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>
149
150 <p>TODO: explain variables and cache. Move explanation here from
151 #options section.</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]152
153</div>
154
155<!-- *********************************************************************** -->
156<div class="doc_section">
157 <a name="options">Options and variables</a>
158</div>
159<!-- *********************************************************************** -->
160
161<div class="doc_text">
162
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>
166
167 <div class="doc_code">
168 <p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p>
169 </div>
170
171 <p>You can set a variable after the initial CMake invocation for
172 changing its value. You can also undefine a variable:</p>
173
174 <div class="doc_code">
175 <p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p>
176 </div>
177
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>
181
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
184 line:</p>
185
186 <div class="doc_code">
187 <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
188 </div>
189
190</div>
191
192<!-- ======================================================================= -->
193<div class="doc_subsection">
194 <a name="freccmake">Frequently-used CMake variables</a>
195</div>
196
197<div class="doc_text">
198
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>.
203
204<dl>
205 <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
206
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
210 settings.</dd>
211
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>
215
216 <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
217 <dd>Flag indicating is shared libraries will be built. Its default
218 value is OFF. Shared libraries are not supported on Windows and
219 not recommended in the other OSes.</dd>
220</dl>
221
222</div>
223
224<!-- ======================================================================= -->
225<div class="doc_subsection">
226 <a name="llvmvars">LLVM-specific variables</a>
227</div>
228
229<div class="doc_text">
230
231<dl>
232 <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
233 <dd>Semicolon-separated list of targets to build, or <i>all</i> for
234 building all targets. Case-sensitive. For Visual C++ defaults
235 to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
236 <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd>
237
238 <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
239 <dd>Build with threads support, if available. Defaults to ON.</dd>
240
241 <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
242 <dd>Add the <i>-fPIC</i> flag to the compiler command-line, if the
243 compiler supports this flag. Some systems, like Windows, does not
244 need this flag. Defaults to OFF.</dd>
245
246 <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
247 <dd>Build 32-bits executables and libraries on 64-bits systems. This
248 option is available only on some 64-bits unix systems. Defaults to
249 OFF.</dd>
250
251 <dt><b>LLVM_PLO_FLAGS</b>:STRING</dt>
252 <dd>Extra flags for creating partially linked objects. Visual C++
253 does not use this.</dd>
254
255 <dt><b>LLVM_TABLEGEN</b>:STRING</dt>
256 <dd>Full path to a native TableGen executable (usually
257 named <i>tblgen</i>). This is intented for cross-compiling: if the
258 user sets this variable, no native TableGen will be created.</dd>
259</dl>
260
261</div>
262
263<!-- *********************************************************************** -->
264<div class="doc_section">
265 <a name="testing">Executing the test suite</a>
266</div>
267<!-- *********************************************************************** -->
268
269<div class="doc_text">
270
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]271<p>LLVM testing is not supported on Visual Studio.</p>
272
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]273<p>TODO</p>
274
275</div>
276
277<!-- *********************************************************************** -->
278<div class="doc_section">
279 <a name="cross">Cross compiling</a>
280</div>
281<!-- *********************************************************************** -->
282
283<div class="doc_text">
284
285<p>TODO</p>
286
287</div>
288
289<!-- *********************************************************************** -->
290<div class="doc_section">
291 <a name="embedding">Embedding LLVM in your project</a>
292</div>
293<!-- *********************************************************************** -->
294
295<div class="doc_text">
296
297<p>TODO</p>
298
299</div>
300
301<!-- *********************************************************************** -->
302
303<hr>
304<address>
305 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
306 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
307 <a href="http://validator.w3.org/check/referer"><img
308 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
309
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]310 <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]311 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
312 Last modified: $Date: 2008-10-27 00:59:36 +0100 (Mon, 27 Oct 2008) $
313</address>
314
315</body>
316</html>