67dfef36247cf36e183c61e365a32d904b975b2f
[oota-llvm.git] / docs / CMake.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2                       "http://www.w3.org/TR/html4/strict.dtd">
3 <html>
4 <head>
5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6   <title>Building LLVM with CMake</title>
7   <link rel="stylesheet" href="_static/llvm.css" type="text/css">
8 </head>
9
10 <h1>
11   Building LLVM with CMake
12 </h1>
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>
19     <ul>
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>
26     <ul>
27     <li><a href="#passdev">Developing LLVM pass out of source</a></li>
28   </ul></li>
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>
33 </ul>
34
35 <div class="doc_author">
36 <p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p>
37 </div>
38
39 <!-- *********************************************************************** -->
40 <h2>
41 <a name="intro">Introduction</a>
42 </h2>
43 <!-- *********************************************************************** -->
44
45 <div>
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
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.
60 </div>
61
62 <!-- *********************************************************************** -->
63 <h2>
64 <a name="quickstart">Quick start</a>
65 </h2>
66 <!-- *********************************************************************** -->
67
68 <div>
69
70 <p> We use here the command-line, non-interactive CMake interface </p>
71
72 <ol>
73
74   <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a>
75       and install CMake. Version 2.8 is the minimum required.</p>
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 <!-- *********************************************************************** -->
116 <h2>
117   <a name="usage">Basic CMake usage</a>
118 </h2>
119 <!-- *********************************************************************** -->
120
121 <div>
122
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">
148       <p><tt>cmake -G "Visual Studio 9 2008" path/to/llvm/source/root</tt></p>
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>
160
161 </div>
162
163 <!-- *********************************************************************** -->
164 <h2>
165   <a name="options">Options and variables</a>
166 </h2>
167 <!-- *********************************************************************** -->
168
169 <div>
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
187     named <tt>CMakeCache.txt</tt> on the root of the build
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
198 <!-- ======================================================================= -->
199 <h3>
200   <a name="freccmake">Frequently-used CMake variables</a>
201 </h3>
202
203 <div>
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
208   --help-variable VARIABLE_NAME</i>.</p>
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
214     values are Release, Debug, RelWithDebInfo and MinSizeRel. On
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
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
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
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 <!-- ======================================================================= -->
242 <h3>
243   <a name="llvmvars">LLVM-specific variables</a>
244 </h3>
245
246 <div>
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:
253     <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"</i>.</dd>
254
255   <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt>
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>
261
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
267   <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt>
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>
271
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
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
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
297   <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
298   <dd>Build with threads support, if available. Defaults to ON.</dd>
299
300   <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt>
301   <dd>Enables code assertions. Defaults to OFF if and only if
302     CMAKE_BUILD_TYPE is <i>Release</i>.</dd>
303
304   <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
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>
308
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
320   <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
321   <dd>Build 32-bits executables and libraries on 64-bits systems. This
322     option is available only on some 64-bits unix systems. Defaults to
323     OFF.</dd>
324
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
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>
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>
343
344   <dt><b>LLVM_LIT_TOOLS_DIR</b>:PATH</dt>
345   <dd>The path to GnuWin32 tools for tests. Valid on Windows host.
346     Defaults to "", then Lit seeks tools according to %PATH%.
347     Lit can find tools(eg. grep, sort, &amp;c) on LLVM_LIT_TOOLS_DIR at first,
348     without specifying GnuWin32 to %PATH%.</dd>
349
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>
355
356   <dt><b>LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR</b>:PATH</dt>
357   <dd>Path to {Clang,lld,Polly}'s source directory. Defaults to
358     tools/{clang,lld,polly}. {Clang,lld,Polly} will not be built when it is
359     empty or it does not point valid path.</dd>
360
361   <dt><b>LLVM_USE_OPROFILE</b>:BOOL</dt>
362   <dd> Enable building OProfile JIT support. Defaults to OFF</dd>
363
364   <dt><b>LLVM_USE_INTEL_JITEVENTS</b>:BOOL</dt>
365   <dd> Enable building support for Intel JIT Events API. Defaults to OFF</dd>
366
367   <dt><b>LLVM_INTEL_JITEVENTS_DIR</b>:PATH</dt>
368   <dd> Path to installation of Intel(R) VTune(TM) Amplifier XE 2011,
369     used to locate the <tt>jitprofiling</tt> library. Default =
370     <tt>%VTUNE_AMPLIFIER_XE_2011_DIR%</tt> (Windows)
371     | <tt>/opt/intel/vtune_amplifier_xe_2011</tt> (Linux) </dd>
372
373 </dl>
374
375 </div>
376
377 </div>
378
379 <!-- *********************************************************************** -->
380 <h2>
381   <a name="testing">Executing the test suite</a>
382 </h2>
383 <!-- *********************************************************************** -->
384
385 <div>
386
387 <p>Testing is performed when the <i>check</i> target is built. For
388   instance, if you are using makefiles, execute this command while on
389   the top level of your build directory:</p>
390
391 <div class="doc_code">
392   <p><tt>make check</tt></p>
393 </div>
394
395 <p>On Visual Studio, you may run tests to build the project "check".</p>
396
397 </div>
398
399 <!-- *********************************************************************** -->
400 <h2>
401   <a name="cross">Cross compiling</a>
402 </h2>
403 <!-- *********************************************************************** -->
404
405 <div>
406
407 <p>See <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling">this
408     wiki page</a> for generic instructions on how to cross-compile
409     with CMake. It goes into detailed explanations and may seem
410     daunting, but it is not. On the wiki page there are several
411     examples including toolchain files. Go directly to
412     <a href="http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains">this
413     section</a> for a quick solution.</p>
414
415 <p>Also see the <a href="#llvmvars">LLVM-specific variables</a>
416   section for variables used when cross-compiling.</p>
417
418 </div>
419
420 <!-- *********************************************************************** -->
421 <h2>
422   <a name="embedding">Embedding LLVM in your project</a>
423 </h2>
424 <!-- *********************************************************************** -->
425
426 <div>
427
428   <p>The most difficult part of adding LLVM to the build of a project
429     is to determine the set of LLVM libraries corresponding to the set
430     of required LLVM features. What follows is an example of how to
431     obtain this information:</p>
432
433   <div class="doc_code">
434     <pre>
435     <b># A convenience variable:</b>
436     set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.")
437     <b># A bit of a sanity check:</b>
438     if( NOT EXISTS ${LLVM_ROOT}/include/llvm )
439     message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install")
440     endif()
441     <b># We incorporate the CMake features provided by LLVM:</b>
442     set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake")
443     include(LLVMConfig)
444     <b># Now set the header and library paths:</b>
445     include_directories( ${LLVM_INCLUDE_DIRS} )
446     link_directories( ${LLVM_LIBRARY_DIRS} )
447     add_definitions( ${LLVM_DEFINITIONS} )
448     <b># Let's suppose we want to build a JIT compiler with support for
449     # binary code (no interpreter):</b>
450     llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
451     <b># Finally, we link the LLVM libraries to our executable:</b>
452     target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
453     </pre>
454   </div>
455
456   <p>This assumes that LLVM_ROOT points to an install of LLVM. The
457     procedure works too for uninstalled builds although we need to take
458     care to add an <i>include_directories</i> for the location of the
459     headers on the LLVM source directory (if we are building
460     out-of-source.)</p>
461
462   <p>Alternativaly, you can utilize CMake's <i>find_package</i>
463     functionality. Here is an equivalent variant of snippet shown above:</p>
464
465   <div class="doc_code">
466     <pre>
467     find_package(LLVM)
468
469     if( NOT LLVM_FOUND )
470       message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
471     endif()
472
473     include_directories( ${LLVM_INCLUDE_DIRS} )
474     link_directories( ${LLVM_LIBRARY_DIRS} )
475
476     llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
477
478     target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
479     </pre>
480   </div>
481
482 <!-- ======================================================================= -->
483 <h3>
484   <a name="passdev">Developing LLVM pass out of source</a>
485 </h3>
486
487 <div>
488
489   <p>It is possible to develop LLVM passes against installed LLVM.
490      An example of project layout provided below:</p>
491
492   <div class="doc_code">
493     <pre>
494       &lt;project dir&gt;/
495           |
496           CMakeLists.txt
497           &lt;pass name&gt;/
498               |
499               CMakeLists.txt
500               Pass.cpp
501               ...
502     </pre>
503   </div>
504
505   <p>Contents of &lt;project dir&gt;/CMakeLists.txt:</p>
506
507   <div class="doc_code">
508     <pre>
509     find_package(LLVM)
510
511     <b># Define add_llvm_* macro's.</b>
512     include(AddLLVM)
513
514     add_definitions(${LLVM_DEFINITIONS})
515     include_directories(${LLVM_INCLUDE_DIRS})
516     link_directories(${LLVM_LIBRARY_DIRS})
517
518     add_subdirectory(&lt;pass name&gt;)
519     </pre>
520   </div>
521
522   <p>Contents of &lt;project dir&gt;/&lt;pass name&gt;/CMakeLists.txt:</p>
523
524   <div class="doc_code">
525     <pre>
526     add_llvm_loadable_module(LLVMPassname
527       Pass.cpp
528       )
529     </pre>
530   </div>
531
532   <p>When you are done developing your pass, you may wish to integrate it
533      into LLVM source tree. You can achieve it in two easy steps:<br>
534      1. Copying &lt;pass name&gt; folder into &lt;LLVM root&gt;/lib/Transform directory.<br>
535      2. Adding "add_subdirectory(&lt;pass name&gt;)" line into &lt;LLVM root&gt;/lib/Transform/CMakeLists.txt</p>
536 </div>
537 <!-- *********************************************************************** -->
538
539 </div>
540
541 <!-- *********************************************************************** -->
542 <h2>
543   <a name="specifics">Compiler/Platform specific topics</a>
544 </h2>
545 <!-- *********************************************************************** -->
546
547 <div>
548
549 <p>Notes for specific compilers and/or platforms.</p>
550
551 <h3>
552   <a name="msvc">Microsoft Visual C++</a>
553 </h3>
554
555 <div>
556
557 <dl>
558   <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
559   <dd>Specifies the maximum number of parallell compiler jobs to use
560     per project when building with msbuild or Visual Studio. Only supported for
561     Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
562     processors. Default is 0.</dd>
563 </dl>
564
565 </div>
566
567 </div>
568
569 <!-- *********************************************************************** -->
570
571 <hr>
572 <address>
573   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
574   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
575   <a href="http://validator.w3.org/check/referer"><img
576   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
577
578   <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
579   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
580   Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
581 </address>
582
583 </body>
584 </html>