1 ========================
2 Building LLVM with CMake
3 ========================
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
12 does not build the project, it generates the files needed by your build tool
13 (GNU make, Visual Studio, etc.) for building LLVM.
15 If you are really anxious about getting a functional LLVM build, go to the
16 `Quick start`_ section. If you are a CMake novice, start with `Basic CMake usage`_
17 and then go back to the `Quick start`_ section once you know what you are doing. The
18 `Options and variables`_ section is a reference for customizing your build. If
19 you already have experience with CMake, this is the recommended starting point.
26 We use here the command-line, non-interactive CMake interface.
28 #. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
29 CMake. Version 2.8.8 is the minimum required, but if you're using the Ninja
30 backend, CMake v3.2 or newer is required to `get interactive output
31 <http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20141117/244797.html>`_
32 when running :doc:`Lit <CommandGuide/lit>`.
34 #. Open a shell. Your development tools must be reachable from this shell
35 through the PATH environment variable.
37 #. Create a build directory. Building LLVM in the source
38 directory is not supported. cd to this directory:
40 .. code-block:: console
45 #. Execute this command in the shell replacing `path/to/llvm/source/root` with
46 the path to the root of your LLVM source tree:
48 .. code-block:: console
50 $ cmake path/to/llvm/source/root
52 CMake will detect your development environment, perform a series of tests, and
53 generate the files required for building LLVM. CMake will use default values
54 for all build parameters. See the `Options and variables`_ section for
55 a list of build parameters that you can modify.
57 This can fail if CMake can't detect your toolset, or if it thinks that the
58 environment is not sane enough. In this case, make sure that the toolset that
59 you intend to use is the only one reachable from the shell, and that the shell
60 itself is the correct one for your development environment. CMake will refuse
61 to build MinGW makefiles if you have a POSIX shell reachable through the PATH
62 environment variable, for instance. You can force CMake to use a given build
63 tool; for instructions, see the `Usage`_ section, below.
65 #. After CMake has finished running, proceed to use IDE project files, or start
66 the build from the build directory:
68 .. code-block:: console
72 The ``--build`` option tells ``cmake`` to invoke the underlying build
73 tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)
75 The underlying build tool can be invoked directly, of course, but
76 the ``--build`` option is portable.
78 #. After LLVM has finished building, install it from the build directory:
80 .. code-block:: console
82 $ cmake --build . --target install
84 The ``--target`` option with ``install`` parameter in addition to
85 the ``--build`` option tells ``cmake`` to build the ``install`` target.
87 It is possible to set a different install prefix at installation time
88 by invoking the ``cmake_install.cmake`` script generated in the
91 .. code-block:: console
93 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
95 .. _Basic CMake usage:
101 This section explains basic aspects of CMake
102 which you may need in your day-to-day usage.
104 CMake comes with extensive documentation, in the form of html files, and as
105 online help accessible via the ``cmake`` executable itself. Execute ``cmake
106 --help`` for further help options.
108 CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
109 or Xcode). If not specified on the command line, CMake tries to guess which
110 build tool to use, based on your environment. Once it has identified your
111 build tool, CMake uses the corresponding *Generator* to create files for your
112 build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can
113 explicitly specify the generator with the command line option ``-G "Name of the
114 generator"``. To see a list of the available generators on your system, execute
116 .. code-block:: console
120 This will list the generator names at the end of the help text.
122 Generators' names are case-sensitive, and may contain spaces. For this reason,
123 you should enter them exactly as they are listed in the ``cmake --help``
124 output, in quotes. For example, to generate project files specifically for
125 Visual Studio 12, you can execute:
127 .. code-block:: console
129 $ cmake -G "Visual Studio 12" path/to/llvm/source/root
131 For a given development platform there can be more than one adequate
132 generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use
133 for building with NMake. By default, CMake chooses the most specific generator
134 supported by your development environment. If you want an alternative generator,
135 you must tell this to CMake with the ``-G`` option.
139 Explain variables and cache. Move explanation here from #options section.
141 .. _Options and variables:
143 Options and variables
144 =====================
146 Variables customize how the build will be generated. Options are boolean
147 variables, with possible values ON/OFF. Options and variables are defined on the
148 CMake command line like this:
150 .. code-block:: console
152 $ cmake -DVARIABLE=value path/to/llvm/source
154 You can set a variable after the initial CMake invocation to change its
155 value. You can also undefine a variable:
157 .. code-block:: console
159 $ cmake -UVARIABLE path/to/llvm/source
161 Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``
162 stored at the root of your build directory that is generated by ``cmake``.
163 Editing it yourself is not recommended.
165 Variables are listed in the CMake cache and later in this document with
166 the variable name and type separated by a colon. You can also specify the
167 variable and type on the CMake command line:
169 .. code-block:: console
171 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
173 Frequently-used CMake variables
174 -------------------------------
176 Here are some of the CMake variables that are used often, along with a
177 brief explanation and LLVM-specific notes. For full documentation, consult the
178 CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
180 **CMAKE_BUILD_TYPE**:STRING
181 Sets the build type for ``make``-based generators. Possible values are
182 Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
183 Visual Studio, you should use the IDE settings to set the build type.
185 **CMAKE_INSTALL_PREFIX**:PATH
186 Path where LLVM will be installed if "make install" is invoked or the
187 "install" target is built.
189 **LLVM_LIBDIR_SUFFIX**:STRING
190 Extra suffix to append to the directory where libraries are to be
191 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
192 to install libraries to ``/usr/lib64``.
194 **CMAKE_C_FLAGS**:STRING
195 Extra flags to use when compiling C source files.
197 **CMAKE_CXX_FLAGS**:STRING
198 Extra flags to use when compiling C++ source files.
200 .. _LLVM-specific variables:
202 LLVM-specific variables
203 -----------------------
205 **LLVM_TARGETS_TO_BUILD**:STRING
206 Semicolon-separated list of targets to build, or *all* for building all
207 targets. Case-sensitive. Defaults to *all*. Example:
208 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
210 **LLVM_BUILD_TOOLS**:BOOL
211 Build LLVM tools. Defaults to ON. Targets for building each tool are generated
212 in any case. You can build a tool separately by invoking its target. For
213 example, you can build *llvm-as* with a Makefile-based system by executing *make
214 llvm-as* at the root of your build directory.
216 **LLVM_INCLUDE_TOOLS**:BOOL
217 Generate build targets for the LLVM tools. Defaults to ON. You can use this
218 option to disable the generation of build targets for the LLVM tools.
220 **LLVM_BUILD_EXAMPLES**:BOOL
221 Build LLVM examples. Defaults to OFF. Targets for building each example are
222 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
225 **LLVM_INCLUDE_EXAMPLES**:BOOL
226 Generate build targets for the LLVM examples. Defaults to ON. You can use this
227 option to disable the generation of build targets for the LLVM examples.
229 **LLVM_BUILD_TESTS**:BOOL
230 Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
231 are generated in any case. You can build a specific unit test using the
232 targets defined under *unittests*, such as ADTTests, IRTests, SupportTests,
233 etc. (Search for ``add_llvm_unittest`` in the subdirectories of *unittests*
234 for a complete list of unit tests.) It is possible to build all unit tests
235 with the target *UnitTests*.
237 **LLVM_INCLUDE_TESTS**:BOOL
238 Generate build targets for the LLVM unit tests. Defaults to ON. You can use
239 this option to disable the generation of build targets for the LLVM unit
242 **LLVM_APPEND_VC_REV**:BOOL
243 Append version control revision info (svn revision number or Git revision id)
244 to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
245 cmake must be invoked before the build. Defaults to OFF.
247 **LLVM_ENABLE_THREADS**:BOOL
248 Build with threads support, if available. Defaults to ON.
250 **LLVM_ENABLE_CXX1Y**:BOOL
251 Build in C++1y mode, if available. Defaults to OFF.
253 **LLVM_ENABLE_ASSERTIONS**:BOOL
254 Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
257 **LLVM_ENABLE_EH**:BOOL
258 Build LLVM with exception-handling support. This is necessary if you wish to
259 link against LLVM libraries and make use of C++ exceptions in your own code
260 that need to propagate through LLVM code. Defaults to OFF.
262 **LLVM_ENABLE_PIC**:BOOL
263 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
264 this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
266 **LLVM_ENABLE_RTTI**:BOOL
267 Build LLVM with run-time type information. Defaults to OFF.
269 **LLVM_ENABLE_WARNINGS**:BOOL
270 Enable all compiler warnings. Defaults to ON.
272 **LLVM_ENABLE_PEDANTIC**:BOOL
273 Enable pedantic mode. This disables compiler-specific extensions, if
274 possible. Defaults to ON.
276 **LLVM_ENABLE_WERROR**:BOOL
277 Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
279 **LLVM_ABI_BREAKING_CHECKS**:STRING
280 Used to decide if LLVM should be built with ABI breaking checks or
281 not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
282 `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
283 assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
284 (off) irrespective of whether normal (`NDEBUG`-based) assertions are
285 enabled or not. A version of LLVM built with ABI breaking checks
286 is not ABI compatible with a version built without it.
288 **LLVM_BUILD_32_BITS**:BOOL
289 Build 32-bit executables and libraries on 64-bit systems. This option is
290 available only on some 64-bit Unix systems. Defaults to OFF.
292 **LLVM_TARGET_ARCH**:STRING
293 LLVM target to use for native code generation. This is required for JIT
294 generation. It defaults to "host", meaning that it shall pick the architecture
295 of the machine where LLVM is being built. If you are cross-compiling, set it
296 to the target architecture name.
298 **LLVM_TABLEGEN**:STRING
299 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
300 intended for cross-compiling: if the user sets this variable, no native
301 TableGen will be created.
303 **LLVM_LIT_ARGS**:STRING
304 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
305 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
308 **LLVM_LIT_TOOLS_DIR**:PATH
309 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
310 the empty string, in which case lit will look for tools needed for tests
311 (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
312 %PATH%, then you can set this variable to the GnuWin32 directory so that
313 lit can find tools needed for tests in that directory.
315 **LLVM_ENABLE_FFI**:BOOL
316 Indicates whether the LLVM Interpreter will be linked with the Foreign Function
317 Interface library (libffi) in order to enable calling external functions.
318 If the library or its headers are installed in a custom
319 location, you can also set the variables FFI_INCLUDE_DIR and
320 FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
321 respectively. Defaults to OFF.
323 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
324 These variables specify the path to the source directory for the external
325 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
326 source directory. If the in-tree subdirectory for an external project
327 exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
328 will not be used. If the variable for an external project does not point
329 to a valid path, then that project will not be built.
331 **LLVM_USE_OPROFILE**:BOOL
332 Enable building OProfile JIT support. Defaults to OFF.
334 **LLVM_PROFDATA_FILE**:PATH
335 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
336 can only be specified if you're building with clang.
338 **LLVM_USE_INTEL_JITEVENTS**:BOOL
339 Enable building support for Intel JIT Events API. Defaults to OFF.
341 **LLVM_ENABLE_ZLIB**:BOOL
342 Enable building with zlib to support compression/uncompression in LLVM tools.
345 **LLVM_USE_SANITIZER**:STRING
346 Define the sanitizer used to build LLVM binaries and tests. Possible values
347 are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
348 and ``Address;Undefined``. Defaults to empty string.
350 **LLVM_PARALLEL_COMPILE_JOBS**:STRING
351 Define the maximum number of concurrent compilation jobs.
353 **LLVM_PARALLEL_LINK_JOBS**:STRING
354 Define the maximum number of concurrent link jobs.
356 **LLVM_BUILD_DOCS**:BOOL
357 Enables all enabled documentation targets (i.e. Doxgyen and Sphinx targets) to
358 be built as part of the normal build. If the ``install`` target is run then
359 this also enables all built documentation targets to be installed. Defaults to
362 **LLVM_ENABLE_DOXYGEN**:BOOL
363 Enables the generation of browsable HTML documentation using doxygen.
366 **LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
367 Enables the generation of a Qt Compressed Help file. Defaults to OFF.
368 This affects the make target ``doxygen-llvm``. When enabled, apart from
369 the normal HTML output generated by doxygen, this will produce a QCH file
370 named ``org.llvm.qch``. You can then load this file into Qt Creator.
371 This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
372 otherwise this has no effect.
374 **LLVM_DOXYGEN_QCH_FILENAME**:STRING
375 The filename of the Qt Compressed Help file that will be generated when
376 ``-DLLVM_ENABLE_DOXYGEN=ON`` and
377 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
379 This option is only useful in combination with
380 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
381 otherwise it has no effect.
383 **LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
384 Namespace under which the intermediate Qt Help Project file lives. See `Qt
386 for more information. Defaults to "org.llvm". This option is only useful in
387 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
390 **LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
391 See `Qt Help Project`_ for
392 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
393 is a combination of the package name and version string. This filter can then
394 be used in Qt Creator to select only documentation from LLVM when browsing
395 through all the help files that you might have loaded. This option is only
396 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
397 otherwise it has no effect.
399 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
401 **LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
402 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
403 ``find_program()`` can find. This option is only useful in combination with
404 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
407 **LLVM_DOXYGEN_SVG**:BOOL
408 Uses .svg files instead of .png files for graphs in the Doxygen output.
411 **LLVM_ENABLE_SPHINX**:BOOL
412 If enabled CMake will search for the ``sphinx-build`` executable and will make
413 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
416 **SPHINX_EXECUTABLE**:STRING
417 The path to the ``sphinx-build`` executable detected by CMake.
419 **SPHINX_OUTPUT_HTML**:BOOL
420 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
421 building the documentation as html are added (but not built by default unless
422 ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
423 source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
424 and ``docs-lld-html``). Defaults to ON.
426 **SPHINX_OUTPUT_MAN**:BOOL
427 If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
428 the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
429 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
432 **SPHINX_WARNINGS_AS_ERRORS**:BOOL
433 If enabled then sphinx documentation warnings will be treated as
434 errors. Defaults to ON.
436 **LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
437 OS X Only: If enabled CMake will generate a target named
438 'install-xcode-toolchain'. This target will create a directory at
439 $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
440 be used to override the default system tools.
442 **LLVM_BUILD_LLVM_DYLIB**:BOOL
443 If enabled, the target for building the libLLVM shared library is added.
444 This library contains all of LLVM's components in a single shared library.
445 Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS.
446 Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB
448 The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS
449 to a list of the desired components.
451 **LLVM_LINK_LLVM_DYLIB**:BOOL
452 If enabled, tools will be linked with the libLLVM shared library. Defaults
453 to OFF. Setting LLVM_LINK_LLVM_DYLIB to ON also sets LLVM_BUILD_LLVM_DYLIB
456 **BUILD_SHARED_LIBS**:BOOL
457 Flag indicating if each LLVM component (e.g. Support) is built as a shared
458 library (ON) or as a static library (OFF). Its default value is OFF. On
459 Windows, shared libraries may be used when building with MinGW, including
460 mingw-w64, but not when building with the Microsoft toolchain.
462 .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
463 If you want to build LLVM as a shared library, you should use the
464 ``LLVM_BUILD_LLVM_DYLIB`` option.
466 Executing the test suite
467 ========================
469 Testing is performed when the *check-all* target is built. For instance, if you are
470 using Makefiles, execute this command in the root of your build directory:
472 .. code-block:: console
476 On Visual Studio, you may run tests by building the project "check-all".
477 For more information about testing, see the :doc:`TestingGuide`.
482 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
483 generic instructions on how to cross-compile with CMake. It goes into detailed
484 explanations and may seem daunting, but it is not. On the wiki page there are
485 several examples including toolchain files. Go directly to `this section
486 <http://www.vtk.org/Wiki/CMake_Cross_Compiling#Information_how_to_set_up_various_cross_compiling_toolchains>`_
487 for a quick solution.
489 Also see the `LLVM-specific variables`_ section for variables used when
492 Embedding LLVM in your project
493 ==============================
495 From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
496 LLVM libraries as importable CMake targets. This means that clients of LLVM can
497 now reliably use CMake to develop their own LLVM-based projects against an
498 installed version of LLVM regardless of how it was built.
500 Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries
501 and uses them to build a simple application ``simple-tool``.
503 .. code-block:: cmake
505 cmake_minimum_required(VERSION 2.8.8)
506 project(SimpleProject)
508 find_package(LLVM REQUIRED CONFIG)
510 message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
511 message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
513 # Set your project compile flags.
514 # E.g. if using the C++ header files
515 # you will need to enable C++11 support
518 include_directories(${LLVM_INCLUDE_DIRS})
519 add_definitions(${LLVM_DEFINITIONS})
521 # Now build our tools
522 add_executable(simple-tool tool.cpp)
524 # Find the libraries that correspond to the LLVM components
525 # that we wish to use
526 llvm_map_components_to_libnames(llvm_libs support core irreader)
528 # Link against LLVM libraries
529 target_link_libraries(simple-tool ${llvm_libs})
531 The ``find_package(...)`` directive when used in CONFIG mode (as in the above
532 example) will look for the ``LLVMConfig.cmake`` file in various locations (see
533 cmake manual for details). It creates a ``LLVM_DIR`` cache entry to save the
534 directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
535 directory (e.g. by passing ``-DLLVM_DIR=/usr/share/llvm/cmake`` to
536 the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
538 This file is available in two different locations.
540 * ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where
541 ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
542 On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
544 * ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
545 ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only
546 available when building LLVM with CMake.**
548 If LLVM is installed in your operating system's normal installation prefix (e.g.
549 on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
550 automatically find LLVM if it is installed correctly. If LLVM is not installed
551 or you wish to build directly against the LLVM build tree you can use
552 ``LLVM_DIR`` as previously mentioned.
554 The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
558 The path to the LLVM CMake directory (i.e. the directory containing
562 A list of preprocessor defines that should be used when building against LLVM.
564 ``LLVM_ENABLE_ASSERTIONS``
565 This is set to ON if LLVM was built with assertions, otherwise OFF.
568 This is set to ON if LLVM was built with exception handling (EH) enabled,
572 This is set to ON if LLVM was built with run time type information (RTTI),
575 ``LLVM_INCLUDE_DIRS``
576 A list of include paths to directories containing LLVM header files.
578 ``LLVM_PACKAGE_VERSION``
579 The LLVM version. This string can be used with CMake conditionals, e.g., ``if
580 (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
582 ``LLVM_TOOLS_BINARY_DIR``
583 The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
585 Notice that in the above example we link ``simple-tool`` against several LLVM
586 libraries. The list of libraries is determined by using the
587 ``llvm_map_components_to_libnames()`` CMake function. For a list of available
588 components look at the output of running ``llvm-config --components``.
590 Note that for LLVM < 3.5 ``llvm_map_components_to_libraries()`` was
591 used instead of ``llvm_map_components_to_libnames()``. This is now deprecated
592 and will be removed in a future version of LLVM.
594 .. _cmake-out-of-source-pass:
596 Developing LLVM passes out of source
597 ------------------------------------
599 It is possible to develop LLVM passes out of LLVM's source tree (i.e. against an
600 installed or built LLVM). An example of a project layout is provided below.
613 Contents of ``<project dir>/CMakeLists.txt``:
615 .. code-block:: cmake
617 find_package(LLVM REQUIRED CONFIG)
619 add_definitions(${LLVM_DEFINITIONS})
620 include_directories(${LLVM_INCLUDE_DIRS})
622 add_subdirectory(<pass name>)
624 Contents of ``<project dir>/<pass name>/CMakeLists.txt``:
626 .. code-block:: cmake
628 add_library(LLVMPassname MODULE Pass.cpp)
630 Note if you intend for this pass to be merged into the LLVM source tree at some
631 point in the future it might make more sense to use LLVM's internal
632 ``add_llvm_loadable_module`` function instead by...
635 Adding the following to ``<project dir>/CMakeLists.txt`` (after
636 ``find_package(LLVM ...)``)
638 .. code-block:: cmake
640 list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
643 And then changing ``<project dir>/<pass name>/CMakeLists.txt`` to
645 .. code-block:: cmake
647 add_llvm_loadable_module(LLVMPassname
651 When you are done developing your pass, you may wish to integrate it
652 into the LLVM source tree. You can achieve it in two easy steps:
654 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
656 #. Adding ``add_subdirectory(<pass name>)`` line into
657 ``<LLVM root>/lib/Transform/CMakeLists.txt``.
659 Compiler/Platform-specific topics
660 =================================
662 Notes for specific compilers and/or platforms.
667 **LLVM_COMPILER_JOBS**:STRING
668 Specifies the maximum number of parallel compiler jobs to use per project
669 when building with msbuild or Visual Studio. Only supported for the Visual
670 Studio 2010 CMake generator. 0 means use all processors. Default is 0.