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="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>"-sv --no-progress-bar"</tt> 341 on Visual C++ and Xcode, 342 <tt>"-sv"</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, &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_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> 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 <project dir>/ 495 | 496 CMakeLists.txt 497 <pass name>/ 498 | 499 CMakeLists.txt 500 Pass.cpp 501 ... 502 </pre> 503 </div> 504 505 <p>Contents of <project dir>/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(<pass name>) 519 </pre> 520 </div> 521 522 <p>Contents of <project dir>/<pass name>/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 <pass name> folder into <LLVM root>/lib/Transform directory.<br> 535 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/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> 585