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="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 8 2005" 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_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 </dl>
 361
 362 </div>
 363
 364 </div>
 365
 366 <!-- *********************************************************************** -->
 367 <h2>
 368   <a name="testing">Executing the test suite</a>
 369 </h2>
 370 <!-- *********************************************************************** -->
 371
 372 <div>
 373
 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>
 377
 378 <div class="doc_code">
 379   <p><tt>make check</tt></p>
 380 </div>
 381
 382 <p>On Visual Studio, you may run tests to build the project "check".</p>
 383
 384 </div>
 385
 386 <!-- *********************************************************************** -->
 387 <h2>
 388   <a name="cross">Cross compiling</a>
 389 </h2>
 390 <!-- *********************************************************************** -->
 391
 392 <div>
 393
 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>
 401
 402 <p>Also see the <a href="#llvmvars">LLVM-specific variables</a>
 403   section for variables used when cross-compiling.</p>
 404
 405 </div>
 406
 407 <!-- *********************************************************************** -->
 408 <h2>
 409   <a name="embedding">Embedding LLVM in your project</a>
 410 </h2>
 411 <!-- *********************************************************************** -->
 412
 413 <div>
 414
 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")
 430     include(LLVMConfig)
 431     <b># Now set the header and library paths:</b>
 432     include_directories( ${LLVM_INCLUDE_DIRS} )
 433     link_directories( ${LLVM_LIBRARY_DIRS} )
 434     add_definitions( ${LLVM_DEFINITIONS} )
 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>
 448
 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
 469 <!-- ======================================================================= -->
 470 <h3>
 471   <a name="passdev">Developing LLVM pass out of source</a>
 472 </h3>
 473
 474 <div>
 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>
 524 <!-- *********************************************************************** -->
 525
 526 </div>
 527
 528 <!-- *********************************************************************** -->
 529 <h2>
 530   <a name="specifics">Compiler/Platform specific topics</a>
 531 </h2>
 532 <!-- *********************************************************************** -->
 533
 534 <div>
 535
 536 <p>Notes for specific compilers and/or platforms.</p>
 537
 538 <h3>
 539   <a name="msvc">Microsoft Visual C++</a>
 540 </h3>
 541
 542 <div>
 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
 554 </div>
 555
 556 <!-- *********************************************************************** -->
 557
 558 <hr>
 559 <address>
 560   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 561   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
 562   <a href="http://validator.w3.org/check/referer"><img
 563   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 564
 565   <a href="mailto:ofv@wanadoo.es">Oscar Fuentes</a><br>
 566   <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
 567   Last modified: $Date: 2010-08-09 03:59:36 +0100 (Mon, 9 Aug 2010) $
 568 </address>
 569
 570 </body>
 571 </html>