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 class="doc_text">
  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 class="doc_text">
  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 class="doc_text">
 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 class="doc_text">
 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 </div>
 198
 199 <!-- ======================================================================= -->
 200 <h3>
 201   <a name="freccmake">Frequently-used CMake variables</a>
 202 </h3>
 203
 204 <div class="doc_text">
 205
 206 <p>Here are listed some of the CMake variables that are used often,
 207   along with a brief explanation and LLVM-specific notes. For full
 208   documentation, check the CMake docs or execute <i>cmake
 209   --help-variable VARIABLE_NAME</i>.</p>
 210
 211 <dl>
 212   <dt><b>CMAKE_BUILD_TYPE</b>:STRING</dt>
 213
 214   <dd>Sets the build type for <i>make</i> based generators. Possible
 215     values are Release, Debug, RelWithDebInfo and MinSizeRel. On
 216     systems like Visual Studio the user sets the build type with the IDE
 217     settings.</dd>
 218
 219   <dt><b>CMAKE_INSTALL_PREFIX</b>:PATH</dt>
 220   <dd>Path where LLVM will be installed if "make install" is invoked
 221     or the "INSTALL" target is built.</dd>
 222
 223   <dt><b>LLVM_LIBDIR_SUFFIX</b>:STRING</dt>
 224   <dd>Extra suffix to append to the directory where libraries are to
 225     be installed. On a 64-bit architecture, one could use
 226     -DLLVM_LIBDIR_SUFFIX=64 to install libraries to /usr/lib64.</dd>
 227
 228   <dt><b>CMAKE_C_FLAGS</b>:STRING</dt>
 229   <dd>Extra flags to use when compiling C source files.</dd>
 230
 231   <dt><b>CMAKE_CXX_FLAGS</b>:STRING</dt>
 232   <dd>Extra flags to use when compiling C++ source files.</dd>
 233
 234   <dt><b>BUILD_SHARED_LIBS</b>:BOOL</dt>
 235   <dd>Flag indicating is shared libraries will be built. Its default
 236     value is OFF. Shared libraries are not supported on Windows and
 237     not recommended in the other OSes.</dd>
 238 </dl>
 239
 240 </div>
 241
 242 <!-- ======================================================================= -->
 243 <h3>
 244   <a name="llvmvars">LLVM-specific variables</a>
 245 </h3>
 246
 247 <div class="doc_text">
 248
 249 <dl>
 250   <dt><b>LLVM_TARGETS_TO_BUILD</b>:STRING</dt>
 251   <dd>Semicolon-separated list of targets to build, or <i>all</i> for
 252     building all targets. Case-sensitive. For Visual C++ defaults
 253     to <i>X86</i>. On the other cases defaults to <i>all</i>. Example:
 254     <i>-DLLVM_TARGETS_TO_BUILD="X86;PowerPC;Alpha"</i>.</dd>
 255
 256   <dt><b>LLVM_BUILD_TOOLS</b>:BOOL</dt>
 257   <dd>Build LLVM tools. Defaults to ON. Targets for building each tool
 258     are generated in any case. You can build an tool separately by
 259     invoking its target. For example, you can build <i>llvm-as</i>
 260     with a makefile-based system executing <i>make llvm-as</i> on the
 261     root of your build directory.</dd>
 262
 263   <dt><b>LLVM_INCLUDE_TOOLS</b>:BOOL</dt>
 264   <dd>Generate build targets for the LLVM tools. Defaults to
 265     ON. You can use that option for disabling the generation of build
 266     targets for the LLVM tools.</dd>
 267
 268   <dt><b>LLVM_BUILD_EXAMPLES</b>:BOOL</dt>
 269   <dd>Build LLVM examples. Defaults to OFF. Targets for building each
 270     example are generated in any case. See documentation
 271     for <i>LLVM_BUILD_TOOLS</i> above for more details.</dd>
 272
 273   <dt><b>LLVM_INCLUDE_EXAMPLES</b>:BOOL</dt>
 274   <dd>Generate build targets for the LLVM examples. Defaults to
 275     ON. You can use that option for disabling the generation of build
 276     targets for the LLVM examples.</dd>
 277
 278   <dt><b>LLVM_BUILD_TESTS</b>:BOOL</dt>
 279   <dd>Build LLVM unit tests. Defaults to OFF. Targets for building
 280     each unit test are generated in any case. You can build a specific
 281     unit test with the target <i>UnitTestNameTests</i> (where at this
 282     time <i>UnitTestName</i> can be ADT, Analysis, ExecutionEngine,
 283     JIT, Support, Transform, VMCore; see the subdirectories
 284     of <i>unittests</i> for an updated list.) It is possible to build
 285     all unit tests with the target <i>UnitTests</i>.</dd>
 286
 287   <dt><b>LLVM_INCLUDE_TESTS</b>:BOOL</dt>
 288   <dd>Generate build targets for the LLVM unit tests. Defaults to
 289     ON. You can use that option for disabling the generation of build
 290     targets for the LLVM unit tests.</dd>
 291
 292   <dt><b>LLVM_APPEND_VC_REV</b>:BOOL</dt>
 293   <dd>Append version control revision info (svn revision number or git
 294     revision id) to LLVM version string (stored in the PACKAGE_VERSION
 295     macro). For this to work cmake must be invoked before the
 296     build. Defaults to OFF.</dd>
 297
 298   <dt><b>LLVM_ENABLE_THREADS</b>:BOOL</dt>
 299   <dd>Build with threads support, if available. Defaults to ON.</dd>
 300
 301   <dt><b>LLVM_ENABLE_ASSERTIONS</b>:BOOL</dt>
 302   <dd>Enables code assertions. Defaults to OFF if and only if
 303     CMAKE_BUILD_TYPE is <i>Release</i>.</dd>
 304
 305   <dt><b>LLVM_ENABLE_PIC</b>:BOOL</dt>
 306   <dd>Add the <i>-fPIC</i> flag for the compiler command-line, if the
 307     compiler supports this flag. Some systems, like Windows, do not
 308     need this flag. Defaults to ON.</dd>
 309
 310   <dt><b>LLVM_ENABLE_WARNINGS</b>:BOOL</dt>
 311   <dd>Enable all compiler warnings. Defaults to ON.</dd>
 312
 313   <dt><b>LLVM_ENABLE_PEDANTIC</b>:BOOL</dt>
 314   <dd>Enable pedantic mode. This disable compiler specific extensions, is
 315     possible. Defaults to ON.</dd>
 316
 317   <dt><b>LLVM_ENABLE_WERROR</b>:BOOL</dt>
 318   <dd>Stop and fail build, if a compiler warning is
 319     triggered. Defaults to OFF.</dd>
 320
 321   <dt><b>LLVM_BUILD_32_BITS</b>:BOOL</dt>
 322   <dd>Build 32-bits executables and libraries on 64-bits systems. This
 323     option is available only on some 64-bits unix systems. Defaults to
 324     OFF.</dd>
 325
 326   <dt><b>LLVM_TARGET_ARCH</b>:STRING</dt>
 327   <dd>LLVM target to use for native code generation. This is required
 328     for JIT generation. It defaults to "host", meaning that it shall
 329     pick the architecture of the machine where LLVM is being built. If
 330     you are cross-compiling, set it to the target architecture
 331     name.</dd>
 332
 333   <dt><b>LLVM_TABLEGEN</b>:STRING</dt>
 334   <dd>Full path to a native TableGen executable (usually
 335     named <i>tblgen</i>). This is intented for cross-compiling: if the
 336     user sets this variable, no native TableGen will be created.</dd>
 337
 338   <dt><b>LLVM_LIT_ARGS</b>:STRING</dt>
 339   <dd>Arguments given to lit.
 340     <tt>make check</tt> and <tt>make clang-test</tt> are affected.
 341     By default, <tt>&quot;-sv --no-progress-bar&quot;</tt>
 342     on Visual C++ and Xcode,
 343     <tt>&quot;-sv&quot;</tt> on others.</dd>
 344
 345   <dt><b>LLVM_LIT_TOOLS_DIR</b>:STRING</dt>
 346   <dd>The path to GnuWin32 tools for tests. Valid on Windows host.
 347     Defaults to "", then Lit seeks tools according to %PATH%.
 348     Lit can find tools(eg. grep, sort, &amp;c) on LLVM_LIT_TOOLS_DIR at first,
 349     without specifying GnuWin32 to %PATH%.</dd>
 350
 351   <dt><b>LLVM_ENABLE_FFI</b>:BOOL</dt>
 352   <dd>Indicates whether LLVM Interpreter will be linked with Foreign
 353     Function Interface library. If the library or its headers are
 354     installed on a custom location, you can set the variables
 355     FFI_INCLUDE_DIR and FFI_LIBRARY_DIR. Defaults to OFF.</dd>
 356 </dl>
 357
 358 </div>
 359
 360 <!-- *********************************************************************** -->
 361 <h2>
 362   <a name="testing">Executing the test suite</a>
 363 </h2>
 364 <!-- *********************************************************************** -->
 365
 366 <div class="doc_text">
 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 class="doc_text">
 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 class="doc_text">
 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(LLVM)
 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 </div>
 463
 464 <!-- ======================================================================= -->
 465 <h3>
 466   <a name="passdev">Developing LLVM pass out of source</a>
 467 </h3>
 468
 469 <div class="doc_text">
 470
 471   <p>It is possible to develop LLVM passes against installed LLVM.
 472      An example of project layout provided below:</p>
 473
 474   <div class="doc_code">
 475     <pre>
 476       &lt;project dir&gt;/
 477           |
 478           CMakeLists.txt
 479           &lt;pass name&gt;/
 480               |
 481               CMakeLists.txt
 482               Pass.cpp
 483               ...
 484     </pre>
 485   </div>
 486
 487   <p>Contents of &lt;project dir&gt;/CMakeLists.txt:</p>
 488
 489   <div class="doc_code">
 490     <pre>
 491     find_package(LLVM)
 492
 493     <b># Define add_llvm_* macro's.</b>
 494     include(AddLLVM)
 495
 496     add_definitions(${LLVM_DEFINITIONS})
 497     include_directories(${LLVM_INCLUDE_DIRS})
 498     link_directories(${LLVM_LIBRARY_DIRS})
 499
 500     add_subdirectory(&lt;pass name&gt;)
 501     </pre>
 502   </div>
 503
 504   <p>Contents of &lt;project dir&gt;/&lt;pass name&gt;/CMakeLists.txt:</p>
 505
 506   <div class="doc_code">
 507     <pre>
 508     add_llvm_loadable_module(LLVMPassname
 509       Pass.cpp
 510       )
 511     </pre>
 512   </div>
 513
 514   <p>When you are done developing your pass, you may wish to integrate it
 515      into LLVM source tree. You can achieve it in two easy steps:<br>
 516      1. Copying &lt;pass name&gt; folder into &lt;LLVM root&gt;/lib/Transform directory.<br>
 517      2. Adding "add_subdirectory(&lt;pass name&gt;)" line into &lt;LLVM root&gt;/lib/Transform/CMakeLists.txt</p>
 518 </div>
 519 <!-- *********************************************************************** -->
 520
 521 <!-- *********************************************************************** -->
 522 <h2>
 523   <a name="specifics">Compiler/Platform specific topics</a>
 524 </h2>
 525 <!-- *********************************************************************** -->
 526
 527 <div class="doc_text">
 528
 529 <p>Notes for specific compilers and/or platforms.</p>
 530
 531 </div>
 532
 533 <h3>
 534   <a name="msvc">Microsoft Visual C++</a>
 535 </h3>
 536
 537 <div class="doc_text">
 538
 539 <dl>
 540   <dt><b>LLVM_COMPILER_JOBS</b>:STRING</dt>
 541   <dd>Specifies the maximum number of parallell compiler jobs to use
 542     per project when building with msbuild or Visual Studio. Only supported for
 543     Visual Studio 2008 and Visual Studio 2010 CMake generators. 0 means use all
 544     processors. Default is 0.</dd>
 545 </dl>
 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>