Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / e0af2adc182fda5b03be5a7027f375804343c8df / . / docs / CMake.html
blob: 6389c7f22afd5d5115e27a65cd592cc18cb9e96e [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
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]9<h1>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]10 Building LLVM with CMake
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]11</h1>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]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>
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]18 <ul>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]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>
Oscar Fuentes23ba1e42011-04-12 19:40:35 +0000[diff] [blame]25 <ul>
26 <li><a href="#passdev">Developing LLVM pass out of source</a></li>
27 </ul></li>
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]28 <li><a href="#specifics">Compiler/Platform specific topics</a>
29 <ul>
30 <li><a href="#msvc">Microsoft Visual C++</a></li>
31 </ul></li>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]32</ul>
33
34<div class="doc_author">
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]35<p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]36</div>
37
38<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]39<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]40<a name="intro">Introduction</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]41</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]42<!-- *********************************************************************** -->
43
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]44<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]45
46 <p><a href="http://www.cmake.org/">CMake</a> is a cross-platform
47 build-generator tool. CMake does not build the project, it generates
48 the files needed by your build tool (GNU make, Visual Studio, etc) for
49 building LLVM.</p>
50
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]51 <p>If you are really anxious about getting a functional LLVM build,
52 go to the <a href="#quickstart">Quick start</a> section. If you
53 are a CMake novice, start on <a href="#usage">Basic CMake
54 usage</a> and then go back to the <a href="#quickstart">Quick
55 start</a> once you know what you are
56 doing. The <a href="#options">Options and variables</a> section
57 is a reference for customizing your build. If you already have
58 experience with CMake, this is the recommended starting point.
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]59</div>
60
61<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]62<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]63<a name="quickstart">Quick start</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]64</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]65<!-- *********************************************************************** -->
66
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]67<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]68
69<p> We use here the command-line, non-interactive CMake interface </p>
70
71<ol>
72
Benjamin Kramere15192b2009-08-05 15:42:44 +0000[diff] [blame]73 <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a>
Oscar Fuentesd1627e32010-11-25 21:41:48 +0000[diff] [blame]74 and install CMake. Version 2.8 is the minimum required.</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]75
76 <li><p>Open a shell. Your development tools must be reachable from this
77 shell through the PATH environment variable.</p>
78
79 <li><p>Create a directory for containing the build. It is not
80 supported to build LLVM on the source directory. cd to this
81 directory:</p>
82 <div class="doc_code">
83 <p><tt>mkdir mybuilddir</tt></p>
84 <p><tt>cd mybuilddir</tt></p>
85 </div>
86
87 <li><p>Execute this command on the shell
88 replacing <i>path/to/llvm/source/root</i> with the path to the
89 root of your LLVM source tree:</p>
90 <div class="doc_code">
91 <p><tt>cmake path/to/llvm/source/root</tt></p>
92 </div>
93
94 <p>CMake will detect your development environment, perform a
95 series of test and generate the files required for building
96 LLVM. CMake will use default values for all build
97 parameters. See the <a href="#options">Options and variables</a>
98 section for fine-tuning your build</p>
99
100 <p>This can fail if CMake can't detect your toolset, or if it
101 thinks that the environment is not sane enough. On this case
102 make sure that the toolset that you intend to use is the only
103 one reachable from the shell and that the shell itself is the
104 correct one for you development environment. CMake will refuse
105 to build MinGW makefiles if you have a POSIX shell reachable
106 through the PATH environment variable, for instance. You can
107 force CMake to use a given build tool, see
108 the <a href="#usage">Usage</a> section.</p>
109
110</ol>
111
112</div>
113
114<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]115<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]116 <a name="usage">Basic CMake usage</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]117</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]118<!-- *********************************************************************** -->
119
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]120<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]121
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]122 <p>This section explains basic aspects of CMake, mostly for
123 explaining those options which you may need on your day-to-day
124 usage.</p>
125
126 <p>CMake comes with extensive documentation in the form of html
127 files and on the cmake executable itself. Execute <i>cmake
128 --help</i> for further help options.</p>
129
130 <p>CMake requires to know for which build tool it shall generate
131 files (GNU make, Visual Studio, Xcode, etc). If not specified on
132 the command line, it tries to guess it based on you
133 environment. Once identified the build tool, CMake uses the
134 corresponding <i>Generator</i> for creating files for your build
135 tool. You can explicitly specify the generator with the command
136 line option <i>-G "Name of the generator"</i>. For knowing the
137 available generators on your platform, execute</p>
138
139 <div class="doc_code">
140 <p><tt>cmake --help</tt></p>
141 </div>
142
143 <p>This will list the generator's names at the end of the help
144 text. Generator's names are case-sensitive. Example:</p>
145
146 <div class="doc_code">
147 <p><tt>cmake -G "Visual Studio 8 2005" path/to/llvm/source/root</tt></p>
148 </div>
149
150 <p>For a given development platform there can be more than one
151 adequate generator. If you use Visual Studio "NMake Makefiles"
152 is a generator you can use for building with NMake. By default,
153 CMake chooses the more specific generator supported by your
154 development environment. If you want an alternative generator,
155 you must tell this to CMake with the <i>-G</i> option.</p>
156
157 <p>TODO: explain variables and cache. Move explanation here from
158 #options section.</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]159
160</div>
161
162<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]163<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]164 <a name="options">Options and variables</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]165</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]166<!-- *********************************************************************** -->
167
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]168<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]169
170 <p>Variables customize how the build will be generated. Options are
171 boolean variables, with possible values ON/OFF. Options and
172 variables are defined on the CMake command line like this:</p>
173
174 <div class="doc_code">
175 <p><tt>cmake -DVARIABLE=value path/to/llvm/source</tt></p>
176 </div>
177
178 <p>You can set a variable after the initial CMake invocation for
179 changing its value. You can also undefine a variable:</p>
180
181 <div class="doc_code">
182 <p><tt>cmake -UVARIABLE path/to/llvm/source</tt></p>
183 </div>
184
185 <p>Variables are stored on the CMake cache. This is a file
Benjamin Kramere15192b2009-08-05 15:42:44 +0000[diff] [blame]186 named <tt>CMakeCache.txt</tt> on the root of the build
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]187 directory. Do not hand-edit it.</p>
188
189 <p>Variables are listed here appending its type after a colon. It is
190 correct to write the variable and the type on the CMake command
191 line:</p>
192
193 <div class="doc_code">
194 <p><tt>cmake -DVARIABLE:TYPE=value path/to/llvm/source</tt></p>
195 </div>
196
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]197<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]198<h3>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]199 <a name="freccmake">Frequently-used CMake variables</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]200</h3>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]201
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]202<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]203
204<p>Here are listed some of the CMake variables that are used often,
205 along with a brief explanation and LLVM-specific notes. For full
206 documentation, check the CMake docs or execute <i>cmake
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]207 --help-variable VARIABLE_NAME</i>.</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]208
209<dl>
210 <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
211
212 <dd>Sets the build type for <i>make</i> based generators. Possible
Oscar Fuentes2ba7a902009-10-21 13:22:20 +0000[diff] [blame]213 values are Release, Debug, RelWithDebInfo and MinSizeRel. On
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]214 systems like Visual Studio the user sets the build type with the IDE
215 settings.</dd>
216
217 <dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt>
218 <dd>Path where LLVM will be installed if "make install" is invoked
219 or the "INSTALL" target is built.</dd>
220
Oscar Fuentesaf0f65f2009-06-12 02:49:53 +0000[diff] [blame]221 <dt><b>LLVM_LIBDIR_SUFFIX</b>:STRING</dt>
222 <dd>Extra suffix to append to the directory where libraries are to
223 be installed. On a 64-bit architecture, one could use
224 -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.</dd>
225
Oscar Fuentesb6c22022008-11-25 04:23:36 +0000[diff] [blame]226 <dt><b>CMAKE_C_FLAGS</b>:STRING</dt>
227 <dd>Extra flags to use when compiling C source files.</dd>
228
229 <dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt>
230 <dd>Extra flags to use when compiling C++ source files.</dd>
231
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]232 <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
233 <dd>Flag indicating is shared libraries will be built. Its default
234 value is OFF. Shared libraries are not supported on Windows and
235 not recommended in the other OSes.</dd>
236</dl>
237
238</div>
239
240<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]241<h3>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]242 <a name="llvmvars">LLVM-specific variables</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]243</h3>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]244
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]245<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]246
247<dl>
248 <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
249 <dd>Semicolon-separated list of targets to build, or <i>all</i> for
250 building all targets. Case-sensitive. For Visual C++ defaults
251 to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
252 <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd>
253
Oscar Fuentesc81f56d2009-08-16 20:56:30 +0000[diff] [blame]254 <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt>
Oscar Fuentesb8352de2009-11-23 00:21:43 +0000[diff] [blame]255 <dd>Build LLVM tools. Defaults to ON. Targets for building each tool
256 are generated in any case. You can build an tool separately by
257 invoking its target. For example, you can build <i>llvm-as</i>
258 with a makefile-based system executing <i>make llvm-as</i> on the
259 root of your build directory.</dd>
Oscar Fuentesc81f56d2009-08-16 20:56:30 +0000[diff] [blame]260
Oscar Fuentesa6c1dbd2010-09-25 20:43:06 +0000[diff] [blame]261 <dt><b>LLVM_INCLUDE_TOOLS</b>:BOOL</dt>
262 <dd>Generate build targets for the LLVM tools. Defaults to
263 ON. You can use that option for disabling the generation of build
264 targets for the LLVM tools.</dd>
265
Oscar Fuentesc81f56d2009-08-16 20:56:30 +0000[diff] [blame]266 <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt>
Oscar Fuentesb8352de2009-11-23 00:21:43 +0000[diff] [blame]267 <dd>Build LLVM examples. Defaults to OFF. Targets for building each
268 example are generated in any case. See documentation
269 for <i>LLVM_BUILD_TOOLS</i> above for more details.</dd>
Oscar Fuentesc81f56d2009-08-16 20:56:30 +0000[diff] [blame]270
Oscar Fuentesa6c1dbd2010-09-25 20:43:06 +0000[diff] [blame]271 <dt><b>LLVM_INCLUDE_EXAMPLES</b>:BOOL</dt>
272 <dd>Generate build targets for the LLVM examples. Defaults to
273 ON. You can use that option for disabling the generation of build
274 targets for the LLVM examples.</dd>
275
Oscar Fuentesda975632010-10-28 14:38:35 +0000[diff] [blame]276 <dt><b>LLVM_BUILD_TESTS</b>:BOOL</dt>
277 <dd>Build LLVM unit tests. Defaults to OFF. Targets for building
278 each unit test are generated in any case. You can build a specific
279 unit test with the target <i>UnitTestNameTests</i> (where at this
280 time <i>UnitTestName</i> can be ADT, Analysis, ExecutionEngine,
281 JIT, Support, Transform, VMCore; see the subdirectories
282 of <i>unittests</i> for an updated list.) It is possible to build
283 all unit tests with the target <i>UnitTests</i>.</dd>
284
285 <dt><b>LLVM_INCLUDE_TESTS</b>:BOOL</dt>
286 <dd>Generate build targets for the LLVM unit tests. Defaults to
287 ON. You can use that option for disabling the generation of build
288 targets for the LLVM unit tests.</dd>
289
Oscar Fuentes784a1762010-12-20 09:47:13 +0000[diff] [blame]290 <dt><b>LLVM_APPEND_VC_REV</b>:BOOL</dt>
291 <dd>Append version control revision info (svn revision number or git
292 revision id) to LLVM version string (stored in the PACKAGE_VERSION
293 macro). For this to work cmake must be invoked before the
294 build. Defaults to OFF.</dd>
295
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]296 <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
297 <dd>Build with threads support, if available. Defaults to ON.</dd>
298
Oscar Fuentes76941b22009-06-04 09:26:16 +0000[diff] [blame]299 <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt>
Oscar Fuentes2ba7a902009-10-21 13:22:20 +0000[diff] [blame]300 <dd>Enables code assertions. Defaults to OFF if and only if
Oscar Fuentes81a87552009-06-03 15:11:25 +0000[diff] [blame]301 CMAKE_BUILD_TYPE is <i>Release</i>.</dd>
302
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]303 <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
Oscar Fuentes1e02bf02009-08-18 15:29:35 +0000[diff] [blame]304 <dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the
305 compiler supports this flag. Some systems, like Windows, do not
306 need this flag. Defaults to ON.</dd>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]307
Oscar Fuentesf12a9002009-12-01 02:21:51 +0000[diff] [blame]308 <dt><b>LLVM_ENABLE_WARNINGS</b>:BOOL</dt>
309 <dd>Enable all compiler warnings. Defaults to ON.</dd>
310
311 <dt><b>LLVM_ENABLE_PEDANTIC</b>:BOOL</dt>
312 <dd>Enable pedantic mode. This disable compiler specific extensions, is
313 possible. Defaults to ON.</dd>
314
315 <dt><b>LLVM_ENABLE_WERROR</b>:BOOL</dt>
316 <dd>Stop and fail build, if a compiler warning is
317 triggered. Defaults to OFF.</dd>
318
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]319 <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
320 <dd>Build 32-bits executables and libraries on 64-bits systems. This
Oscar Fuentesf12a9002009-12-01 02:21:51 +0000[diff] [blame]321 option is available only on some 64-bits unix systems. Defaults to
322 OFF.</dd>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]323
Oscar Fuentesa9ff1392009-09-13 22:18:38 +0000[diff] [blame]324 <dt><b>LLVM_TARGET_ARCH</b>:STRING</dt>
325 <dd>LLVM target to use for native code generation. This is required
326 for JIT generation. It defaults to "host", meaning that it shall
327 pick the architecture of the machine where LLVM is being built. If
328 you are cross-compiling, set it to the target architecture
329 name.</dd>
330
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]331 <dt><b>LLVM_TABLEGEN</b>:STRING</dt>
332 <dd>Full path to a native TableGen executable (usually
333 named <i>tblgen</i>). This is intented for cross-compiling: if the
334 user sets this variable, no native TableGen will be created.</dd>
NAKAMURA Takumie7ae70b2010-11-11 04:09:35 +0000[diff] [blame]335
336 <dt><b>LLVM_LIT_ARGS</b>:STRING</dt>
337 <dd>Arguments given to lit.
338 <tt>make check</tt> and <tt>make clang-test</tt> are affected.
339 By default, <tt>&quot;-sv --no-progress-bar&quot;</tt>
340 on Visual C++ and Xcode,
341 <tt>&quot;-sv&quot;</tt> on others.</dd>
Oscar Fuentes59693792011-01-21 15:42:54 +0000[diff] [blame]342
NAKAMURA Takumie0af2ad2011-10-13 17:36:02 +0000[diff] [blame^]343 <dt><b>LLVM_LIT_TOOLS_DIR</b>:PATH</dt>
NAKAMURA Takumif287f012011-02-09 04:19:28 +0000[diff] [blame]344 <dd>The path to GnuWin32 tools for tests. Valid on Windows host.
345 Defaults to "", then Lit seeks tools according to %PATH%.
NAKAMURA Takumi4d6deb02011-04-09 09:51:57 +0000[diff] [blame]346 Lit can find tools(eg. grep, sort, &amp;c) on LLVM_LIT_TOOLS_DIR at first,
NAKAMURA Takumif287f012011-02-09 04:19:28 +0000[diff] [blame]347 without specifying GnuWin32 to %PATH%.</dd>
348
Oscar Fuentes59693792011-01-21 15:42:54 +0000[diff] [blame]349 <dt><b>LLVM_ENABLE_FFI</b>:BOOL</dt>
350 <dd>Indicates whether LLVM Interpreter will be linked with Foreign
351 Function Interface library. If the library or its headers are
352 installed on a custom location, you can set the variables
353 FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. Defaults to OFF.</dd>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]354</dl>
355
356</div>
357
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]358</div>
359
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]360<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]361<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]362 <a name="testing">Executing the test suite</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]363</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]364<!-- *********************************************************************** -->
365
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]366<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]367
Oscar Fuentesfd2f3e62010-08-09 02:49:39 +0000[diff] [blame]368<p>Testing is performed when the <i>check</i> target is built. For
369 instance, if you are using makefiles, execute this command while on
370 the top level of your build directory:</p>
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]371
Oscar Fuentesfd2f3e62010-08-09 02:49:39 +0000[diff] [blame]372<div class="doc_code">
373 <p><tt>make check</tt></p>
374</div>
375
NAKAMURA Takumif287f012011-02-09 04:19:28 +0000[diff] [blame]376<p>On Visual Studio, you may run tests to build the project "check".</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]377
378</div>
379
380<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]381<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]382 <a name="cross">Cross compiling</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]383</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]384<!-- *********************************************************************** -->
385
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]386<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]387
Oscar Fuentescbdbcb12009-06-11 04:45:08 +0000[diff] [blame]388<p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
389 wiki page</a> for generic instructions on how to cross-compile
390 with CMake. It goes into detailed explanations and may seem
391 daunting, but it is not. On the wiki page there are several
392 examples including toolchain files. Go directly to
393 <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this
394 section</a> for a quick solution.</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]395
Oscar Fuentesa9ff1392009-09-13 22:18:38 +0000[diff] [blame]396<p>Also see the <a href="#llvmvars">LLVM-specific variables</a>
397 section for variables used when cross-compiling.</p>
398
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]399</div>
400
401<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]402<h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]403 <a name="embedding">Embedding LLVM in your project</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]404</h2>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]405<!-- *********************************************************************** -->
406
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]407<div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]408
Oscar Fuentesc2d86882010-08-09 03:26:48 +0000[diff] [blame]409 <p>The most difficult part of adding LLVM to the build of a project
410 is to determine the set of LLVM libraries corresponding to the set
411 of required LLVM features. What follows is an example of how to
412 obtain this information:</p>
413
414 <div class="doc_code">
415 <pre>
416 <b># A convenience variable:</b>
417 set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
418 <b># A bit of a sanity check:</b>
419 if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
420 message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
421 endif()
422 <b># We incorporate the CMake features provided by LLVM:</b>
423 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
Oscar Fuentesd4b0c6c2011-05-01 02:12:20 +0000[diff] [blame]424 include(LLVMConfig)
Oscar Fuentesc2d86882010-08-09 03:26:48 +0000[diff] [blame]425 <b># Now set the header and library paths:</b>
Chandler Carruthcb8d8fa2011-09-04 23:24:13 +0000[diff] [blame]426 include_directories( ${LLVM_INCLUDE_DIRS} )
427 link_directories( ${LLVM_LIBRARY_DIRS} )
428 add_definitions( ${LLVM_DEFINITIONS} )
Oscar Fuentesc2d86882010-08-09 03:26:48 +0000[diff] [blame]429 <b># Let's suppose we want to build a JIT compiler with support for
430 # binary code (no interpreter):</b>
431 llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
432 <b># Finally, we link the LLVM libraries to our executable:</b>
433 target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
434 </pre>
435 </div>
436
437 <p>This assumes that LLVM_ROOT points to an install of LLVM. The
438 procedure works too for uninstalled builds although we need to take
439 care to add an <i>include_directories</i> for the location of the
440 headers on the LLVM source directory (if we are building
441 out-of-source.)</p>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]442
Oscar Fuentes3447b4f2011-04-10 16:17:49 +0000[diff] [blame]443 <p>Alternativaly, you can utilize CMake's <i>find_package</i>
444 functionality. Here is an equivalent variant of snippet shown above:</p>
445
446 <div class="doc_code">
447 <pre>
448 find_package(LLVM)
449
450 if( NOT LLVM_FOUND )
451 message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
452 endif()
453
454 include_directories( ${LLVM_INCLUDE_DIRS} )
455 link_directories( ${LLVM_LIBRARY_DIRS} )
456
457 llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
458
459 target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
460 </pre>
461 </div>
462
Oscar Fuentes23ba1e42011-04-12 19:40:35 +0000[diff] [blame]463<!-- ======================================================================= -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]464<h3>
Oscar Fuentes23ba1e42011-04-12 19:40:35 +0000[diff] [blame]465 <a name="passdev">Developing LLVM pass out of source</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]466</h3>
Oscar Fuentes23ba1e42011-04-12 19:40:35 +0000[diff] [blame]467
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]468<div>
Oscar Fuentes23ba1e42011-04-12 19:40:35 +0000[diff] [blame]469
470 <p>It is possible to develop LLVM passes against installed LLVM.
471 An example of project layout provided below:</p>
472
473 <div class="doc_code">
474 <pre>
475 &lt;project dir&gt;/
476 |
477 CMakeLists.txt
478 &lt;pass name&gt;/
479 |
480 CMakeLists.txt
481 Pass.cpp
482 ...
483 </pre>
484 </div>
485
486 <p>Contents of &lt;project dir&gt;/CMakeLists.txt:</p>
487
488 <div class="doc_code">
489 <pre>
490 find_package(LLVM)
491
492 <b># Define add_llvm_* macro's.</b>
493 include(AddLLVM)
494
495 add_definitions(${LLVM_DEFINITIONS})
496 include_directories(${LLVM_INCLUDE_DIRS})
497 link_directories(${LLVM_LIBRARY_DIRS})
498
499 add_subdirectory(&lt;pass name&gt;)
500 </pre>
501 </div>
502
503 <p>Contents of &lt;project dir&gt;/&lt;pass name&gt;/CMakeLists.txt:</p>
504
505 <div class="doc_code">
506 <pre>
507 add_llvm_loadable_module(LLVMPassname
508 Pass.cpp
509 )
510 </pre>
511 </div>
512
513 <p>When you are done developing your pass, you may wish to integrate it
514 into LLVM source tree. You can achieve it in two easy steps:<br>
515 1. Copying &lt;pass name&gt; folder into &lt;LLVM root&gt;/lib/Transform directory.<br>
516 2. Adding "add_subdirectory(&lt;pass name&gt;)" line into &lt;LLVM root&gt;/lib/Transform/CMakeLists.txt</p>
517</div>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]518<!-- *********************************************************************** -->
519
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]520</div>
521
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]522<!-- *********************************************************************** -->
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]523<h2>
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]524 <a name="specifics">Compiler/Platform specific topics</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]525</h2>
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]526<!-- *********************************************************************** -->
527
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]528<div>
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]529
530<p>Notes for specific compilers and/or platforms.</p>
531
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]532<h3>
Oscar Fuentes0dddbc32011-03-02 17:47:37 +0000[diff] [blame]533 <a name="msvc">Microsoft Visual C++</a>
NAKAMURA Takumi05d02652011-04-18 23:59:50 +0000[diff] [blame]534</h3>
Oscar Fuentes0dddbc32011-03-02 17:47:37 +0000[diff] [blame]535
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]536<div>
Oscar Fuentes0dddbc32011-03-02 17:47:37 +0000[diff] [blame]537
538<dl>
539 <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
540 <dd>Specifies the maximum number of parallell compiler jobs to use
541 per project when building with msbuild or Visual Studio. Only supported for
542 Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
543 processors. Default is 0.</dd>
544</dl>
545
546</div>
547
NAKAMURA Takumif5af6ad2011-04-23 00:30:22 +0000[diff] [blame]548</div>
549
Oscar Fuentes0c913732008-12-31 14:36:41 +0000[diff] [blame]550<!-- *********************************************************************** -->
551
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]552<hr>
553<address>
554 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]555 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]556 <a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]557 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]558
Oscar Fuentes370387c2008-11-20 23:35:09 +0000[diff] [blame]559 <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
NAKAMURA Takumib9a33632011-04-09 02:13:37 +0000[diff] [blame]560 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Oscar Fuentesc2d86882010-08-09 03:26:48 +0000[diff] [blame]561 Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
Oscar Fuentes25f1d032008-11-20 22:05:48 +0000[diff] [blame]562</address>
563
564</body>
565</html>