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