1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 2 "http://www.w3.org/TR/html4/strict.dtd"> 3<html> 4<head> 5 <title>Building LLVM with CMake</title> 6 <link rel="stylesheet" href="llvm.css" type="text/css"> 7</head> 8 9<h1> 10 Building LLVM with CMake 11</h1> 12 13<ul> 14 <li><a href="#intro">Introduction</a></li> 15 <li><a href="#quickstart">Quick start</a></li> 16 <li><a href="#usage">Basic CMake usage</a> 17 <li><a href="#options">Options and variables</a> 18 <ul> 19 <li><a href="#freccmake">Frequently-used CMake variables</a></li> 20 <li><a href="#llvmvars">LLVM-specific variables</a></li> 21 </ul></li> 22 <li><a href="#testing">Executing the test suite</a> 23 <li><a href="#cross">Cross compiling</a> 24 <li><a href="#embedding">Embedding LLVM in your project</a> 25 <ul> 26 <li><a href="#passdev">Developing LLVM pass out of source</a></li> 27 </ul></li> 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> 32</ul> 33 34<div class="doc_author"> 35<p>Written by <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a></p> 36</div> 37 38<!-- *********************************************************************** --> 39<h2> 40<a name="intro">Introduction</a> 41</h2> 42<!-- *********************************************************************** --> 43 44<div> 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 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. 59</div> 60 61<!-- *********************************************************************** --> 62<h2> 63<a name="quickstart">Quick start</a> 64</h2> 65<!-- *********************************************************************** --> 66 67<div> 68 69<p> We use here the command-line, non-interactive CMake interface </p> 70 71<ol> 72 73 <li><p><a href="http://www.cmake.org/cmake/resources/software.html">Download</a> 74 and install CMake. Version 2.8 is the minimum required.</p> 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<!-- *********************************************************************** --> 115<h2> 116 <a name="usage">Basic CMake usage</a> 117</h2> 118<!-- *********************************************************************** --> 119 120<div> 121 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> 159 160</div> 161 162<!-- *********************************************************************** --> 163<h2> 164 <a name="options">Options and variables</a> 165</h2> 166<!-- *********************************************************************** --> 167 168<div> 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 186 named <tt>CMakeCache.txt</tt> on the root of the build 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 197<!-- ======================================================================= --> 198<h3> 199 <a name="freccmake">Frequently-used CMake variables</a> 200</h3> 201 202<div> 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 207 --help-variable VARIABLE_NAME</i>.</p> 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 213 values are Release, Debug, RelWithDebInfo and MinSizeRel. On 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 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 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 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<!-- ======================================================================= --> 241<h3> 242 <a name="llvmvars">LLVM-specific variables</a> 243</h3> 244 245<div> 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 254 <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt> 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> 260 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 266 <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt> 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> 270 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 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 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 296 <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt> 297 <dd>Build with threads support, if available. Defaults to ON.</dd> 298 299 <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt> 300 <dd>Enables code assertions. Defaults to OFF if and only if 301 CMAKE_BUILD_TYPE is <i>Release</i>.</dd> 302 303 <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt> 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> 307 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 319 <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt> 320 <dd>Build 32-bits executables and libraries on 64-bits systems. This 321 option is available only on some 64-bits unix systems. Defaults to 322 OFF.</dd> 323 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 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> 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>"-sv --no-progress-bar"</tt> 340 on Visual C++ and Xcode, 341 <tt>"-sv"</tt> on others.</dd> 342 343 <dt><b>LLVM_LIT_TOOLS_DIR</b>:PATH</dt> 344 <dd>The path to GnuWin32 tools for tests. Valid on Windows host. 345 Defaults to "", then Lit seeks tools according to %PATH%. 346 Lit can find tools(eg. grep, sort, &c) on LLVM_LIT_TOOLS_DIR at first, 347 without specifying GnuWin32 to %PATH%.</dd> 348 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> 354</dl> 355 356</div> 357 358</div> 359 360<!-- *********************************************************************** --> 361<h2> 362 <a name="testing">Executing the test suite</a> 363</h2> 364<!-- *********************************************************************** --> 365 366<div> 367 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> 371 372<div class="doc_code"> 373 <p><tt>make check</tt></p> 374</div> 375 376<p>On Visual Studio, you may run tests to build the project "check".</p> 377 378</div> 379 380<!-- *********************************************************************** --> 381<h2> 382 <a name="cross">Cross compiling</a> 383</h2> 384<!-- *********************************************************************** --> 385 386<div> 387 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> 395 396<p>Also see the <a href="#llvmvars">LLVM-specific variables</a> 397 section for variables used when cross-compiling.</p> 398 399</div> 400 401<!-- *********************************************************************** --> 402<h2> 403 <a name="embedding">Embedding LLVM in your project</a> 404</h2> 405<!-- *********************************************************************** --> 406 407<div> 408 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") 424 include(LLVMConfig) 425 <b># Now set the header and library paths:</b> 426 include_directories( ${LLVM_INCLUDE_DIRS} ) 427 link_directories( ${LLVM_LIBRARY_DIRS} ) 428 add_definitions( ${LLVM_DEFINITIONS} ) 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> 442 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 463<!-- ======================================================================= --> 464<h3> 465 <a name="passdev">Developing LLVM pass out of source</a> 466</h3> 467 468<div> 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 <project dir>/ 476 | 477 CMakeLists.txt 478 <pass name>/ 479 | 480 CMakeLists.txt 481 Pass.cpp 482 ... 483 </pre> 484 </div> 485 486 <p>Contents of <project dir>/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(<pass name>) 500 </pre> 501 </div> 502 503 <p>Contents of <project dir>/<pass name>/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 <pass name> folder into <LLVM root>/lib/Transform directory.<br> 516 2. Adding "add_subdirectory(<pass name>)" line into <LLVM root>/lib/Transform/CMakeLists.txt</p> 517</div> 518<!-- *********************************************************************** --> 519 520</div> 521 522<!-- *********************************************************************** --> 523<h2> 524 <a name="specifics">Compiler/Platform specific topics</a> 525</h2> 526<!-- *********************************************************************** --> 527 528<div> 529 530<p>Notes for specific compilers and/or platforms.</p> 531 532<h3> 533 <a name="msvc">Microsoft Visual C++</a> 534</h3> 535 536<div> 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 548</div> 549 550<!-- *********************************************************************** --> 551 552<hr> 553<address> 554 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img 555 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> 556 <a href="http://validator.w3.org/check/referer"><img 557 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> 558 559 <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br> 560 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> 561 Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $ 562</address> 563 564</body> 565</html> 566