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   <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>&quot;-sv --no-progress-bar&quot;</tt>
 340     on Visual C++ and Xcode,
 341     <tt>&quot;-sv&quot;</tt> on others.</dd>
 342
 343   <dt><b>LLVM_LIT_TOOLS_DIR</b>:STRING</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, &amp;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_ROOT}/include )
 427     link_directories( ${LLVM_ROOT}/lib )
 428     <b># Let's suppose we want to build a JIT compiler with support for
 429     # binary code (no interpreter):</b>
 430     llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 431     <b># Finally, we link the LLVM libraries to our executable:</b>
 432     target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 433     </pre>
 434   </div>
 435
 436   <p>This assumes that LLVM_ROOT points to an install of LLVM. The
 437     procedure works too for uninstalled builds although we need to take
 438     care to add an <i>include_directories</i> for the location of the
 439     headers on the LLVM source directory (if we are building
 440     out-of-source.)</p>
 441
 442   <p>Alternativaly, you can utilize CMake's <i>find_package</i>
 443     functionality. Here is an equivalent variant of snippet shown above:</p>
 444
 445   <div class="doc_code">
 446     <pre>
 447     find_package(LLVM)
 448
 449     if( NOT LLVM_FOUND )
 450       message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.")
 451     endif()
 452
 453     include_directories( ${LLVM_INCLUDE_DIRS} )
 454     link_directories( ${LLVM_LIBRARY_DIRS} )
 455
 456     llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native)
 457
 458     target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES})
 459     </pre>
 460   </div>
 461
 462 <!-- ======================================================================= -->
 463 <h3>
 464   <a name="passdev">Developing LLVM pass out of source</a>
 465 </h3>
 466
 467 <div>
 468
 469   <p>It is possible to develop LLVM passes against installed LLVM.
 470      An example of project layout provided below:</p>
 471
 472   <div class="doc_code">
 473     <pre>
 474       &lt;project dir&gt;/
 475           |
 476           CMakeLists.txt
 477           &lt;pass name&gt;/
 478               |
 479               CMakeLists.txt
 480               Pass.cpp
 481               ...
 482     </pre>
 483   </div>
 484
 485   <p>Contents of &lt;project dir&gt;/CMakeLists.txt:</p>
 486
 487   <div class="doc_code">
 488     <pre>
 489     find_package(LLVM)
 490
 491     <b># Define add_llvm_* macro's.</b>
 492     include(AddLLVM)
 493
 494     add_definitions(${LLVM_DEFINITIONS})
 495     include_directories(${LLVM_INCLUDE_DIRS})
 496     link_directories(${LLVM_LIBRARY_DIRS})
 497
 498     add_subdirectory(&lt;pass name&gt;)
 499     </pre>
 500   </div>
 501
 502   <p>Contents of &lt;project dir&gt;/&lt;pass name&gt;/CMakeLists.txt:</p>
 503
 504   <div class="doc_code">
 505     <pre>
 506     add_llvm_loadable_module(LLVMPassname
 507       Pass.cpp
 508       )
 509     </pre>
 510   </div>
 511
 512   <p>When you are done developing your pass, you may wish to integrate it
 513      into LLVM source tree. You can achieve it in two easy steps:<br>
 514      1. Copying &lt;pass name&gt; folder into &lt;LLVM root&gt;/lib/Transform directory.<br>
 515      2. Adding "add_subdirectory(&lt;pass name&gt;)" line into &lt;LLVM root&gt;/lib/Transform/CMakeLists.txt</p>
 516 </div>
 517 <!-- *********************************************************************** -->
 518
 519 </div>
 520
 521 <!-- *********************************************************************** -->
 522 <h2>
 523   <a name="specifics">Compiler/Platform specific topics</a>
 524 </h2>
 525 <!-- *********************************************************************** -->
 526
 527 <div>
 528
 529 <p>Notes for specific compilers and/or platforms.</p>
 530
 531 <h3>
 532   <a name="msvc">Microsoft Visual C++</a>
 533 </h3>
 534
 535 <div>
 536
 537 <dl>
 538   <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
 539   <dd>Specifies the maximum number of parallell compiler jobs to use
 540     per project when building with msbuild or Visual Studio. Only supported for
 541     Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
 542     processors. Default is 0.</dd>
 543 </dl>
 544
 545 </div>
 546
 547 </div>
 548
 549 <!-- *********************************************************************** -->
 550
 551 <hr>
 552 <address>
 553   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 554   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
 555   <a href="http://validator.w3.org/check/referer"><img
 556   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 557
 558   <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
 559   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
 560   Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
 561 </address>
 562
 563 </body>
 564 </html>