Lines Matching +full:cmake +full:-
2 Building LLVM with CMake
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
20 `Quick start`_ section. If you are a CMake novice, start with `Basic CMake usage`_
23 you already have experience with CMake, this is the recommended starting point.
25 This page is geared towards users of the LLVM CMake build. If you're looking for
26 information about modifying the LLVM CMake build system you may want to see the
27 :doc:`CMakePrimer` page. It has a basic overview of the CMake language.
34 We use here the command-line, non-interactive CMake interface.
36 #. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
37 CMake. Version 3.4.3 is the minimum required.
45 .. code-block:: console
53 .. code-block:: console
55 $ cmake path/to/llvm/source/root
57 CMake will detect your development environment, perform a series of tests, and
58 generate the files required for building LLVM. CMake will use default values
62 This can fail if CMake can't detect your toolset, or if it thinks that the
65 itself is the correct one for your development environment. CMake will refuse
67 environment variable, for instance. You can force CMake to use a given build
70 #. After CMake has finished running, proceed to use IDE project files, or start
73 .. code-block:: console
75 $ cmake --build .
77 The ``--build`` option tells ``cmake`` to invoke the underlying build
81 the ``--build`` option is portable.
85 .. code-block:: console
87 $ cmake --build . --target install
89 The ``--target`` option with ``install`` parameter in addition to
90 the ``--build`` option tells ``cmake`` to build the ``install`` target.
93 by invoking the ``cmake_install.cmake`` script generated in the
96 .. code-block:: console
98 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
100 .. _Basic CMake usage:
103 Basic CMake usage
106 This section explains basic aspects of CMake
107 which you may need in your day-to-day usage.
109 CMake comes with extensive documentation, in the form of html files, and as
110 online help accessible via the ``cmake`` executable itself. Execute ``cmake
111 --help`` for further help options.
113 CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
114 or Xcode). If not specified on the command line, CMake tries to guess which
116 build tool, CMake uses the corresponding *Generator* to create files for your
118 explicitly specify the generator with the command line option ``-G "Name of the
121 .. code-block:: console
123 $ cmake --help
127 Generators' names are case-sensitive, and may contain spaces. For this reason,
128 you should enter them exactly as they are listed in the ``cmake --help``
132 .. code-block:: console
134 $ cmake -G "Visual Studio 12" path/to/llvm/source/root
138 for building with NMake. By default, CMake chooses the most specific generator
140 you must tell this to CMake with the ``-G`` option.
153 CMake command line like this:
155 .. code-block:: console
157 $ cmake -DVARIABLE=value path/to/llvm/source
159 You can set a variable after the initial CMake invocation to change its
162 .. code-block:: console
164 $ cmake -UVARIABLE path/to/llvm/source
166 Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``
167 stored at the root of your build directory that is generated by ``cmake``.
170 Variables are listed in the CMake cache and later in this document with
172 variable and type on the CMake command line:
174 .. code-block:: console
176 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
178 Frequently-used CMake variables
179 -------------------------------
181 Here are some of the CMake variables that are used often, along with a
182 brief explanation and LLVM-specific notes. For full documentation, consult the
183 CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
186 Sets the build type for ``make``-based generators. Possible values are
196 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
205 .. _LLVM-specific variables:
207 LLVM-specific variables
208 -----------------------
211 Semicolon-separated list of targets to build, or *all* for building all
212 targets. Case-sensitive. Defaults to *all*. Example:
213 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
218 example, you can build *llvm-as* with a Makefile-based system by executing *make
219 llvm-as* at the root of your build directory.
250 cmake must be invoked before the build. Defaults to OFF.
263 Build LLVM with exception-handling support. This is necessary if you wish to
271 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
275 Build LLVM with run-time type information. Defaults to OFF.
281 Enable pedantic mode. This disables compiler-specific extensions, if
292 (off) irrespective of whether normal (`NDEBUG`-based) assertions are
297 Build 32-bit executables and libraries on 64-bit systems. This option is
298 available only on some 64-bit Unix systems. Defaults to OFF.
303 of the machine where LLVM is being built. If you are cross-compiling, set it
307 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
308 intended for cross-compiling: if the user sets this variable, no native
312 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
313 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
333 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
334 source directory. If the in-tree subdirectory for an external project
340 Semicolon-separated list of additional external projects to build as part of
343 ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar"
344 -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
345 -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.
351 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
367 Add ``-flto`` or ``-flto=`` flags to the compile and link command
368 lines, enabling link-time optimization. Possible values are ``Off``,
391 This affects the make target ``doxygen-llvm``. When enabled, apart from
394 This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
399 ``-DLLVM_ENABLE_DOXYGEN=ON`` and
400 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
403 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
410 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
415 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
419 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
422 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
425 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
427 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
435 If specified, CMake will search for the ``sphinx-build`` executable and will make
436 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
440 The path to the ``sphinx-build`` executable detected by CMake.
446 source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
447 and ``docs-lld-html``). Defaults to ON.
452 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
460 OS X Only: If enabled CMake will generate a target named
461 'install-xcode-toolchain'. This target will create a directory at
483 mingw-w64, but not when building with the Microsoft toolchain.
490 If enabled and building a debug or asserts build the CMake build system will
495 CMake Caches
500 CMake variables passed on the command line. Clang provides a collection of CMake
503 CMake cache files are utilized using CMake's -C flag:
505 .. code-block:: console
507 $ cmake -C <path to cache file> <path to sources>
509 CMake cache scripts are processed in an isolated scope, only cached variables
510 remain set when the main configuration runs. CMake cached variables do not reset
513 A few notes about CMake Caches:
515 - Order of command line arguments is important
517 - -D arguments specified before -C are set before the cache is processed and
519 - -D arguments specified after -C are set after the cache is processed and
522 - All -D arguments will override cache file settings
523 - CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
525 - It is recommended that all -D options should be specified *before* -C
533 Testing is performed when the *check-all* target is built. For instance, if you are
536 .. code-block:: console
538 $ make check-all
540 On Visual Studio, you may run tests by building the project "check-all".
547 generic instructions on how to cross-compile with CMake. It goes into detailed
553 Also see the `LLVM-specific variables`_ section for variables used when
554 cross-compiling.
559 From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
560 LLVM libraries as importable CMake targets. This means that clients of LLVM can
561 now reliably use CMake to develop their own LLVM-based projects against an
565 and uses them to build a simple application ``simple-tool``.
567 .. code-block:: cmake
575 message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
586 add_executable(simple-tool tool.cpp)
593 target_link_libraries(simple-tool ${llvm_libs})
596 example) will look for the ``LLVMConfig.cmake`` file in various locations (see
597 cmake manual for details). It creates a ``LLVM_DIR`` cache entry to save the
598 directory where ``LLVMConfig.cmake`` is found or allows the user to specify the
599 directory (e.g. by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to
600 the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
604 * ``<INSTALL_PREFIX>/lib/cmake/llvm/LLVMConfig.cmake`` where
606 On Linux typically this is ``/usr/lib/cmake/llvm/LLVMConfig.cmake``.
608 * ``<LLVM_BUILD_ROOT>/lib/cmake/llvm/LLVMConfig.cmake`` where
610 available when building LLVM with CMake.**
618 The ``LLVMConfig.cmake`` file sets various useful variables. Notable variables
622 The path to the LLVM CMake directory (i.e. the directory containing
623 LLVMConfig.cmake).
643 The LLVM version. This string can be used with CMake conditionals, e.g., ``if
647 The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
649 Notice that in the above example we link ``simple-tool`` against several LLVM
651 ``llvm_map_components_to_libnames()`` CMake function. For a list of available
652 components look at the output of running ``llvm-config --components``.
658 .. _cmake-out-of-source-pass:
661 ------------------------------------
666 .. code-block:: none
679 .. code-block:: cmake
690 .. code-block:: cmake
702 .. code-block:: cmake
709 .. code-block:: cmake
723 Compiler/Platform-specific topics
729 --------------------
734 Studio 2010 CMake generator. 0 means use all processors. Default is 0.