1.. _building-with-cmake: 2 3======================== 4Building LLVM with CMake 5======================== 6 7.. contents:: 8 :local: 9 10Introduction 11============ 12 13`CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake 14does not build the project, it generates the files needed by your build tool 15(GNU make, Visual Studio, etc) for building LLVM. 16 17If you are really anxious about getting a functional LLVM build, go to the 18`Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_ 19and then go back to the `Quick start`_ once you know what you are doing. The 20`Options and variables`_ section is a reference for customizing your build. If 21you already have experience with CMake, this is the recommended starting point. 22 23.. _Quick start: 24 25Quick start 26=========== 27 28We use here the command-line, non-interactive CMake interface. 29 30#. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install 31 CMake. Version 2.8 is the minimum required. 32 33#. Open a shell. Your development tools must be reachable from this shell 34 through the PATH environment variable. 35 36#. Create a directory for containing the build. It is not supported to build 37 LLVM on the source directory. cd to this directory: 38 39 .. code-block:: bash 40 41 $ mkdir mybuilddir 42 $ cd mybuilddir 43 44#. Execute this command on the shell replacing `path/to/llvm/source/root` with 45 the path to the root of your LLVM source tree: 46 47 .. code-block:: bash 48 49 $ cmake path/to/llvm/source/root 50 51 CMake will detect your development environment, perform a series of test and 52 generate the files required for building LLVM. CMake will use default values 53 for all build parameters. See the `Options and variables`_ section for 54 fine-tuning your build 55 56 This can fail if CMake can't detect your toolset, or if it thinks that the 57 environment is not sane enough. On this case make sure that the toolset that 58 you intend to use is the only one reachable from the shell and that the shell 59 itself is the correct one for you development environment. CMake will refuse 60 to build MinGW makefiles if you have a POSIX shell reachable through the PATH 61 environment variable, for instance. You can force CMake to use a given build 62 tool, see the `Usage`_ section. 63 64.. _Basic CMake usage: 65.. _Usage: 66 67Basic CMake usage 68================= 69 70This section explains basic aspects of CMake, mostly for explaining those 71options which you may need on your day-to-day usage. 72 73CMake comes with extensive documentation in the form of html files and on the 74cmake executable itself. Execute ``cmake --help`` for further help options. 75 76CMake requires to know for which build tool it shall generate files (GNU make, 77Visual Studio, Xcode, etc). If not specified on the command line, it tries to 78guess it based on you environment. Once identified the build tool, CMake uses 79the corresponding *Generator* for creating files for your build tool. You can 80explicitly specify the generator with the command line option ``-G "Name of the 81generator"``. For knowing the available generators on your platform, execute 82 83.. code-block:: bash 84 85 $ cmake --help 86 87This will list the generator's names at the end of the help text. Generator's 88names are case-sensitive. Example: 89 90.. code-block:: bash 91 92 $ cmake -G "Visual Studio 9 2008" path/to/llvm/source/root 93 94For a given development platform there can be more than one adequate 95generator. If you use Visual Studio "NMake Makefiles" is a generator you can use 96for building with NMake. By default, CMake chooses the more specific generator 97supported by your development environment. If you want an alternative generator, 98you must tell this to CMake with the ``-G`` option. 99 100.. todo:: 101 102 Explain variables and cache. Move explanation here from #options section. 103 104.. _Options and variables: 105 106Options and variables 107===================== 108 109Variables customize how the build will be generated. Options are boolean 110variables, with possible values ON/OFF. Options and variables are defined on the 111CMake command line like this: 112 113.. code-block:: bash 114 115 $ cmake -DVARIABLE=value path/to/llvm/source 116 117You can set a variable after the initial CMake invocation for changing its 118value. You can also undefine a variable: 119 120.. code-block:: bash 121 122 $ cmake -UVARIABLE path/to/llvm/source 123 124Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt`` 125on the root of the build directory. Do not hand-edit it. 126 127Variables are listed here appending its type after a colon. It is correct to 128write the variable and the type on the CMake command line: 129 130.. code-block:: bash 131 132 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source 133 134Frequently-used CMake variables 135------------------------------- 136 137Here are listed some of the CMake variables that are used often, along with a 138brief explanation and LLVM-specific notes. For full documentation, check the 139CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 140 141**CMAKE_BUILD_TYPE**:STRING 142 Sets the build type for ``make`` based generators. Possible values are 143 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 144 the user sets the build type with the IDE settings. 145 146**CMAKE_INSTALL_PREFIX**:PATH 147 Path where LLVM will be installed if "make install" is invoked or the 148 "INSTALL" target is built. 149 150**LLVM_LIBDIR_SUFFIX**:STRING 151 Extra suffix to append to the directory where libraries are to be 152 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 153 to install libraries to ``/usr/lib64``. 154 155**CMAKE_C_FLAGS**:STRING 156 Extra flags to use when compiling C source files. 157 158**CMAKE_CXX_FLAGS**:STRING 159 Extra flags to use when compiling C++ source files. 160 161**BUILD_SHARED_LIBS**:BOOL 162 Flag indicating is shared libraries will be built. Its default value is 163 OFF. Shared libraries are not supported on Windows and not recommended in the 164 other OSes. 165 166.. _LLVM-specific variables: 167 168LLVM-specific variables 169----------------------- 170 171**LLVM_TARGETS_TO_BUILD**:STRING 172 Semicolon-separated list of targets to build, or *all* for building all 173 targets. Case-sensitive. For Visual C++ defaults to *X86*. On the other cases 174 defaults to *all*. Example: ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``. 175 176**LLVM_BUILD_TOOLS**:BOOL 177 Build LLVM tools. Defaults to ON. Targets for building each tool are generated 178 in any case. You can build an tool separately by invoking its target. For 179 example, you can build *llvm-as* with a makefile-based system executing *make 180 llvm-as* on the root of your build directory. 181 182**LLVM_INCLUDE_TOOLS**:BOOL 183 Generate build targets for the LLVM tools. Defaults to ON. You can use that 184 option for disabling the generation of build targets for the LLVM tools. 185 186**LLVM_BUILD_EXAMPLES**:BOOL 187 Build LLVM examples. Defaults to OFF. Targets for building each example are 188 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more 189 details. 190 191**LLVM_INCLUDE_EXAMPLES**:BOOL 192 Generate build targets for the LLVM examples. Defaults to ON. You can use that 193 option for disabling the generation of build targets for the LLVM examples. 194 195**LLVM_BUILD_TESTS**:BOOL 196 Build LLVM unit tests. Defaults to OFF. Targets for building each unit test 197 are generated in any case. You can build a specific unit test with the target 198 *UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis, 199 ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of 200 *unittests* for an updated list.) It is possible to build all unit tests with 201 the target *UnitTests*. 202 203**LLVM_INCLUDE_TESTS**:BOOL 204 Generate build targets for the LLVM unit tests. Defaults to ON. You can use 205 that option for disabling the generation of build targets for the LLVM unit 206 tests. 207 208**LLVM_APPEND_VC_REV**:BOOL 209 Append version control revision info (svn revision number or git revision id) 210 to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work 211 cmake must be invoked before the build. Defaults to OFF. 212 213**LLVM_ENABLE_THREADS**:BOOL 214 Build with threads support, if available. Defaults to ON. 215 216**LLVM_ENABLE_ASSERTIONS**:BOOL 217 Enables code assertions. Defaults to OFF if and only if ``CMAKE_BUILD_TYPE`` 218 is *Release*. 219 220**LLVM_ENABLE_PIC**:BOOL 221 Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports 222 this flag. Some systems, like Windows, do not need this flag. Defaults to ON. 223 224**LLVM_ENABLE_WARNINGS**:BOOL 225 Enable all compiler warnings. Defaults to ON. 226 227**LLVM_ENABLE_PEDANTIC**:BOOL 228 Enable pedantic mode. This disable compiler specific extensions, is 229 possible. Defaults to ON. 230 231**LLVM_ENABLE_WERROR**:BOOL 232 Stop and fail build, if a compiler warning is triggered. Defaults to OFF. 233 234**LLVM_BUILD_32_BITS**:BOOL 235 Build 32-bits executables and libraries on 64-bits systems. This option is 236 available only on some 64-bits unix systems. Defaults to OFF. 237 238**LLVM_TARGET_ARCH**:STRING 239 LLVM target to use for native code generation. This is required for JIT 240 generation. It defaults to "host", meaning that it shall pick the architecture 241 of the machine where LLVM is being built. If you are cross-compiling, set it 242 to the target architecture name. 243 244**LLVM_TABLEGEN**:STRING 245 Full path to a native TableGen executable (usually named ``tblgen``). This is 246 intended for cross-compiling: if the user sets this variable, no native 247 TableGen will be created. 248 249**LLVM_LIT_ARGS**:STRING 250 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 251 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 252 others. 253 254**LLVM_LIT_TOOLS_DIR**:PATH 255 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to "", 256 then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep, sort, 257 &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%. 258 259**LLVM_ENABLE_FFI**:BOOL 260 Indicates whether LLVM Interpreter will be linked with Foreign Function 261 Interface library. If the library or its headers are installed on a custom 262 location, you can set the variables FFI_INCLUDE_DIR and 263 FFI_LIBRARY_DIR. Defaults to OFF. 264 265**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH 266 Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to 267 ``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it 268 is empty or it does not point valid path. 269 270**LLVM_USE_OPROFILE**:BOOL 271 Enable building OProfile JIT support. Defaults to OFF 272 273**LLVM_USE_INTEL_JITEVENTS**:BOOL 274 Enable building support for Intel JIT Events API. Defaults to OFF 275 276Executing the test suite 277======================== 278 279Testing is performed when the *check* target is built. For instance, if you are 280using makefiles, execute this command while on the top level of your build 281directory: 282 283.. code-block:: bash 284 285 $ make check 286 287On Visual Studio, you may run tests to build the project "check". 288 289Cross compiling 290=============== 291 292See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for 293generic instructions on how to cross-compile with CMake. It goes into detailed 294explanations and may seem daunting, but it is not. On the wiki page there are 295several examples including toolchain files. Go directly to `this section 296<http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_ 297for a quick solution. 298 299Also see the `LLVM-specific variables`_ section for variables used when 300cross-compiling. 301 302Embedding LLVM in your project 303============================== 304 305The most difficult part of adding LLVM to the build of a project is to determine 306the set of LLVM libraries corresponding to the set of required LLVM 307features. What follows is an example of how to obtain this information: 308 309.. code-block:: cmake 310 311 # A convenience variable: 312 set(LLVM_ROOT "" CACHE PATH "Root of LLVM install.") 313 314 # A bit of a sanity check: 315 if( NOT EXISTS ${LLVM_ROOT}/include/llvm ) 316 message(FATAL_ERROR "LLVM_ROOT (${LLVM_ROOT}) is not a valid LLVM install") 317 endif() 318 319 # We incorporate the CMake features provided by LLVM: 320 set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${LLVM_ROOT}/share/llvm/cmake") 321 include(LLVMConfig) 322 323 # Now set the header and library paths: 324 include_directories( ${LLVM_INCLUDE_DIRS} ) 325 link_directories( ${LLVM_LIBRARY_DIRS} ) 326 add_definitions( ${LLVM_DEFINITIONS} ) 327 328 # Let's suppose we want to build a JIT compiler with support for 329 # binary code (no interpreter): 330 llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) 331 332 # Finally, we link the LLVM libraries to our executable: 333 target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) 334 335This assumes that LLVM_ROOT points to an install of LLVM. The procedure works 336too for uninstalled builds although we need to take care to add an 337`include_directories` for the location of the headers on the LLVM source 338directory (if we are building out-of-source.) 339 340Alternativaly, you can utilize CMake's ``find_package`` functionality. Here is 341an equivalent variant of snippet shown above: 342 343.. code-block:: cmake 344 345 find_package(LLVM) 346 347 if( NOT LLVM_FOUND ) 348 message(FATAL_ERROR "LLVM package can't be found. Set CMAKE_PREFIX_PATH variable to LLVM's installation prefix.") 349 endif() 350 351 include_directories( ${LLVM_INCLUDE_DIRS} ) 352 link_directories( ${LLVM_LIBRARY_DIRS} ) 353 354 llvm_map_components_to_libraries(REQ_LLVM_LIBRARIES jit native) 355 356 target_link_libraries(mycompiler ${REQ_LLVM_LIBRARIES}) 357 358Developing LLVM pass out of source 359---------------------------------- 360 361It is possible to develop LLVM passes against installed LLVM. An example of 362project layout provided below: 363 364.. code-block:: bash 365 366 <project dir>/ 367 | 368 CMakeLists.txt 369 <pass name>/ 370 | 371 CMakeLists.txt 372 Pass.cpp 373 ... 374 375Contents of ``<project dir>/CMakeLists.txt``: 376 377.. code-block:: cmake 378 379 find_package(LLVM) 380 381 # Define add_llvm_* macro's. 382 include(AddLLVM) 383 384 add_definitions(${LLVM_DEFINITIONS}) 385 include_directories(${LLVM_INCLUDE_DIRS}) 386 link_directories(${LLVM_LIBRARY_DIRS}) 387 388 add_subdirectory(<pass name>) 389 390Contents of ``<project dir>/<pass name>/CMakeLists.txt``: 391 392.. code-block:: cmake 393 394 add_llvm_loadable_module(LLVMPassname 395 Pass.cpp 396 ) 397 398When you are done developing your pass, you may wish to integrate it 399into LLVM source tree. You can achieve it in two easy steps: 400 401#. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory. 402 403#. Adding ``add_subdirectory(<pass name>)`` line into 404 ``<LLVM root>/lib/Transform/CMakeLists.txt``. 405 406Compiler/Platform specific topics 407================================= 408 409Notes for specific compilers and/or platforms. 410 411Microsoft Visual C++ 412-------------------- 413 414**LLVM_COMPILER_JOBS**:STRING 415 Specifies the maximum number of parallell compiler jobs to use per project 416 when building with msbuild or Visual Studio. Only supported for Visual Studio 417 2008 and Visual Studio 2010 CMake generators. 0 means use all 418 processors. Default is 0. 419