Lines Matching +full:docs +full:- +full:clang +full:- +full:tools +full:- +full:html
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
34 We use here the command-line, non-interactive CMake interface.
36 #. `Download <http://www.cmake.org/cmake/resources/software.html>`_ and install
39 #. Open a shell. Your development tools must be reachable from this shell
45 .. code-block:: console
53 .. code-block:: console
70 components are built; see the `Frequently Used LLVM-related
76 .. code-block:: console
78 $ cmake --build .
80 The ``--build`` option tells ``cmake`` to invoke the underlying build
84 the ``--build`` option is portable.
88 .. code-block:: console
90 $ cmake --build . --target install
92 The ``--target`` option with ``install`` parameter in addition to
93 the ``--build`` option tells ``cmake`` to build the ``install`` target.
99 .. code-block:: console
101 $ cmake -DCMAKE_INSTALL_PREFIX=/tmp/llvm -P cmake_install.cmake
110 which you may need in your day-to-day usage.
112 CMake comes with extensive documentation, in the form of html files, and as
114 --help`` for further help options.
121 explicitly specify the generator with the command line option ``-G "Name of the
124 .. code-block:: console
126 $ cmake --help
130 Generators' names are case-sensitive, and may contain spaces. For this reason,
131 you should enter them exactly as they are listed in the ``cmake --help``
135 .. code-block:: console
137 $ cmake -G "Visual Studio 12" path/to/llvm/source/root
143 you must tell this to CMake with the ``-G`` option.
158 .. code-block:: console
160 $ cmake -DVARIABLE=value path/to/llvm/source
165 .. code-block:: console
167 $ cmake -UVARIABLE path/to/llvm/source
177 .. code-block:: console
179 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
183 Frequently-used CMake variables
184 -------------------------------
188 or execute ``cmake --help-variable VARIABLE_NAME``. See `Frequently
189 Used LLVM-related Variables`_ below for information about commonly
202 **Release** For Speed No No Users of LLVM and Clang
208 * Optimizations make LLVM/Clang run faster, but can be an impediment for
209 step-by-step debugging.
214 down LLVM and Clang when enabled, but can be useful during development.
221 Note: on Windows (building with MSVC or clang-cl), CMake's **RelWithDebInfo**
237 .. _Frequently Used LLVM-related variables:
239 Frequently Used LLVM-related variables
240 --------------------------------------
244 description is in `LLVM-related variables`_ below.
247 Control which projects are enabled. For example you may want to work on clang
248 or lldb by specifying ``-DLLVM_ENABLE_PROJECTS="clang;lldb"``.
252 libc++ or libc++abi by specifying ``-DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi"``.
256 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
264 32GB machine, specify ``-G Ninja -DLLVM_PARALLEL_LINK_JOBS=2``.
268 your native target with, for example, ``-DLLVM_TARGETS_TO_BUILD=X86``.
274 ``-DLLVM_USE_LINKER=lld``.
276 Rarely-used CMake variables
277 ---------------------------
280 explanation and LLVM-related notes. For full documentation, consult the CMake
281 manual, or execute ``cmake --help-variable VARIABLE_NAME``.
303 .. _LLVM-related variables:
305 LLVM-related variables
306 -----------------------
309 enabled sub-projects. Nearly all of these variable names begin with
312 .. _LLVM-related variables BUILD_SHARED_LIBS:
318 mingw-w64, but not when building with the Microsoft toolchain.
329 (off) irrespective of whether normal (`NDEBUG`-based) assertions are
342 need revision info can disable this option to avoid re-linking most binaries
351 This is useful in environments where git is not available or non-functional
355 Build 32-bit executables and libraries on 64-bit systems. This option is
356 available only on some 64-bit Unix systems. Defaults to OFF.
375 If enabled, `source-based code coverage
376 <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation
378 scripts and the llvm-cov and llvm-profdata tools that pair to your compiler,
379 the build will also generate the `generate-coverage-report` target to generate
380 the code coverage report for LLVM, and the `clear-profile-data` utility target
389 Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB
404 Build LLVM tools. Defaults to ON. Targets for building each tool are generated
406 example, you can build *llvm-as* with a Makefile-based system by executing *make
407 llvm-as* at the root of your build directory.
429 'install-xcode-toolchain'. This target will create a directory at
431 be used to override the default system tools.
436 of the machine where LLVM is being built. If you are building a cross-compiler,
441 ``-DLLVM_ENABLE_DOXYGEN=ON`` and
442 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
445 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
451 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
460 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
463 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
469 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
492 of ~0.1%. `COVERAGE` is an ABI-breaking option.
499 Enables the generation of browsable HTML documentation using doxygen.
504 This affects the make target ``doxygen-llvm``. When enabled, apart from
505 the normal HTML output generated by doxygen, this will produce a QCH file
507 This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
511 Build LLVM with exception-handling support. This is necessary if you wish to
527 Enables the optional cpp-httplib dependency which is used by llvm-debuginfod
528 to serve debug info over HTTP. `cpp-httplib <https://github.com/yhirose/cpp-httplib>`_
534 ``install-*`` and ``check-*`` targets, since IDEs don't always deal well with
539 If the host compiler and linker supports the stdlib flag, -stdlib=libc++ is
545 tools.
549 This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage
559 Add ``-flto`` or ``-flto=`` flags to the compile and link command
560 lines, enabling link-time optimization. Possible values are ``Off``,
564 Compile with `Clang Header Modules
565 <https://clang.llvm.org/docs/Modules.html>`_.
570 For Windows builds using MSVC or clang-cl, generate PDB files when
574 Enable pedantic mode. This disables compiler-specific extensions, if
578 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
582 Semicolon-separated list of projects to build, or *all* for building all
583 (clang, lldb, lld, polly, etc) projects. This flag assumes that projects
584 are checked out side-by-side and not nested, i.e. clang needs to be in
585 parallel of llvm instead of nested in ``llvm/tools``. This feature allows
586 to have one build for only LLVM and another for clang+llvm using the same
591 ``bolt;clang;clang-tools-extra;compiler-rt;cross-project-tests;libc;libclc;lld;lldb;mlir;openmp;polly;pstl``
599 Build LLVM with run-time type information. Defaults to OFF.
602 Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler.
606 compiler, see the `libc++ documentation <https://libcxx.llvm.org/VendorDocumentation.html>`_.
613 ``libc;libunwind;libcxxabi;pstl;libcxx;compiler-rt;openmp;llvm-libgcc;offload``
620 If specified, CMake will search for the ``sphinx-build`` executable and will make
638 If enabled, the Z3 constraint solver is activated for the Clang static analyzer.
642 Used to decide if LLVM tools should support compression/decompression with
647 Used to decide if LLVM tools should support compression/decompression with
652 Semicolon-separated list of experimental targets to build and linked into
657 Semicolon-separated list of additional external projects to build as part of
660 ``-DLLVM_EXTERNAL_PROJECTS="Foo;Bar"
661 -DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
662 -DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.
664 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
666 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
667 source directory. If the in-tree subdirectory for an external project
668 exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
699 Generate build targets for the LLVM tools. Defaults to ON. You can use this
700 option to disable the generation of build targets for the LLVM tools.
709 Install symlinks from the binutils tool names to the corresponding LLVM tools.
710 For example, ar will be symlinked to llvm-ar.
713 Install symliks from the cctools tool names to the corresponding LLVM tools.
714 For example, lipo will be symlinked to llvm-lipo.
717 The path to install OCamldoc-generated HTML documentation to. This path can
719 ``${CMAKE_INSTALL_DOCDIR}/llvm/ocaml-html``.
722 The path to install Sphinx-generated HTML documentation to. This path can
724 ``${CMAKE_INSTALL_DOCDIR}/llvm/html``.
731 The path to install Doxygen-generated HTML documentation to. This path can
733 ``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``.
737 tools and libraries. Using a lock-free allocator such as the ones listed below
739 midly improves Clang build times, by about 5-10%. At the moment, rpmalloc,
743 .. code-block:: console
746 $ D:\llvm-project> cmake ... -DLLVM_INTEGRATED_CRT_ALLOC=D:\git\rpmalloc
749 Release target, add -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded.
750 Note that rpmalloc is also supported natively in-tree, see option below.
753 Similar to LLVM_INTEGRATED_CRT_ALLOC, embeds the in-tree rpmalloc into the
759 If enabled, tools will be linked with the libLLVM shared library. Defaults
768 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
769 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
773 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
774 the empty string, in which case lit will look for tools needed for tests
777 lit can find tools needed for tests in that directory.
781 (containing binaries such as ``llvm-tblgen`` and ``clang-tblgen``). This is
782 intended for cross-compiling: if the user sets this variable and the
788 on Darwin in the build tree will be used. Otherwise the install-time library
791 set to non-standard values.
805 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
806 can only be specified if you're building with clang.
817 in a memory-limited environment. Using a
818 ``-DLLVM_RAM_PER_LINK_JOB=10000`` is a good approximation. On ELF
819 platforms debug builds can reduce link-time memory pressure by also
824 reverse order. This is useful for uncovering non-determinism caused by
829 "-static-libstdc++", but a Clang host compiler will statically link to libc++
833 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
834 intended for cross-compiling: if the user sets this variable, no native
840 of the machine where LLVM is being built. If you are cross-compiling, set it
844 Semicolon-separated list of targets to build, or *all* for building all
845 targets. Case-sensitive. Defaults to *all*. Example:
846 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
853 For example, on an x86_64 machine, specifying ``-DLLVM_TARGETS_TO_BUILD=host``
875 Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on
876 your compiler, for clang the value can be an absolute path to your custom
877 linker, otherwise clang will prefix the name with ``ld.`` and apply its usual
879 with ``-DLLVM_USE_LINKER=gold``.
901 If enabled CMake will pass ``-gsplit-dwarf`` to the compiler. This option
902 reduces link-time memory usage by reducing the amount of debug information that
907 The path to the ``sphinx-build`` executable detected by CMake.
909 https://www.sphinx-doc.org/en/master/usage/installation.html
913 building the documentation as html are added (but not built by default unless
915 source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
916 and ``docs-lld-html``). Defaults to ON.
921 is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
940 The path to install the main LLVM tools, relative to the *CMAKE_INSTALL_PREFIX*.
951 Recently LLVM and Clang have been adding some more complicated build system
953 CMake variables passed on the command line. Clang provides a collection of CMake
956 CMake cache files are utilized using CMake's -C flag:
958 .. code-block:: console
960 $ cmake -C <path to cache file> <path to sources>
968 - Order of command line arguments is important
970 - -D arguments specified before -C are set before the cache is processed and
972 - -D arguments specified after -C are set after the cache is processed and
975 - All -D arguments will override cache file settings
976 - CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command
978 - It is recommended that all -D options should be specified *before* -C
986 Testing is performed when the *check-all* target is built. For instance, if you are
989 .. code-block:: console
991 $ make check-all
993 On Visual Studio, you may run tests by building the project "check-all".
1000 generic instructions on how to cross-compile with CMake. It goes into detailed
1006 Also see the `LLVM-related variables`_ section for variables used when
1007 cross-compiling.
1014 CMake to develop their own LLVM-based projects against an installed version of
1018 and uses them to build a simple application ``simple-tool``.
1020 .. code-block:: cmake
1039 # Now build our tools
1040 add_executable(simple-tool tool.cpp)
1047 target_link_libraries(simple-tool ${llvm_libs})
1053 directory (e.g. by passing ``-DLLVM_DIR=/usr/lib/cmake/llvm`` to
1054 the ``cmake`` command or by setting it directly in ``ccmake`` or ``cmake-gui``).
1103 The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
1105 Notice that in the above example we link ``simple-tool`` against several LLVM
1108 components look at the output of running ``llvm-config --components``.
1114 .. _cmake-out-of-source-pass:
1117 ------------------------------------
1122 .. code-block:: none
1135 .. code-block:: cmake
1147 .. code-block:: cmake
1159 .. code-block:: cmake
1166 .. code-block:: cmake
1180 Compiler/Platform-specific topics
1186 -------
1194 When compiling with clang-cl, recent CMake versions will default to selecting
1195 `llvm-mt` as the Manifest Tool instead of Microsoft's `mt.exe`. This will
1198 .. code-block:: console
1200 -- Check for working C compiler: [...]clang-cl.exe - broken
1203 llvm-mt: error: no libxml2