[llvm] f776108 - [docs] Collate CMake options
Nathan Sidwell via llvm-commits
llvm-commits at lists.llvm.org
Wed Jun 9 11:25:00 PDT 2021
Author: Nathan Sidwell
Date: 2021-06-09T11:24:38-07:00
New Revision: f776108168ab0179fe6131576679431bec1f562e
URL: https://github.com/llvm/llvm-project/commit/f776108168ab0179fe6131576679431bec1f562e
DIFF: https://github.com/llvm/llvm-project/commit/f776108168ab0179fe6131576679431bec1f562e.diff
LOG: [docs] Collate CMake options
I found the documentation of the various CMake variables difficult to
navigate, because they are unsorted. I can see they've grown
organically with new clusters of somewhat-related options, but the
result is hard to use. This collates them (treating '_' as space).
Differential Revision: https://reviews.llvm.org/D102481
Added:
Modified:
llvm/docs/CMake.rst
Removed:
################################################################################
diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index c1d1cd0c7c71..f1ac2c7d4934 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -193,17 +193,17 @@ CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
Path where LLVM will be installed if "make install" is invoked or the
"install" target is built.
-**LLVM_LIBDIR_SUFFIX**:STRING
- Extra suffix to append to the directory where libraries are to be
- installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
- to install libraries to ``/usr/lib64``.
-
**CMAKE_C_FLAGS**:STRING
Extra flags to use when compiling C source files.
**CMAKE_CXX_FLAGS**:STRING
Extra flags to use when compiling C++ source files.
+**LLVM_LIBDIR_SUFFIX**:STRING
+ Extra suffix to append to the directory where libraries are to be
+ installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
+ to install libraries to ``/usr/lib64``.
+
Rarely-used CMake variables
---------------------------
@@ -220,42 +220,66 @@ manual, or execute ``cmake --help-variable VARIABLE_NAME``.
LLVM-specific variables
-----------------------
-**LLVM_TARGETS_TO_BUILD**:STRING
- Semicolon-separated list of targets to build, or *all* for building all
- targets. Case-sensitive. Defaults to *all*. Example:
- ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
+**BUILD_SHARED_LIBS**:BOOL
+ Flag indicating if each LLVM component (e.g. Support) is built as a shared
+ library (ON) or as a static library (OFF). Its default value is OFF. On
+ Windows, shared libraries may be used when building with MinGW, including
+ mingw-w64, but not when building with the Microsoft toolchain.
-**LLVM_EXPERIMENTAL_TARGETS_TO_BUILD**:STRING
- Semicolon-separated list of experimental targets to build and linked into
- llvm. This will build the experimental target without needing it to add to the
- list of all the targets available in the LLVM's main CMakeLists.txt.
+ .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
+ If you want to build LLVM as a shared library, you should use the
+ ``LLVM_BUILD_LLVM_DYLIB`` option.
-**LLVM_BUILD_TOOLS**:BOOL
- Build LLVM tools. Defaults to ON. Targets for building each tool are generated
- in any case. You can build a tool separately by invoking its target. For
- example, you can build *llvm-as* with a Makefile-based system by executing *make
- llvm-as* at the root of your build directory.
+**LLVM_ABI_BREAKING_CHECKS**:STRING
+ Used to decide if LLVM should be built with ABI breaking checks or
+ not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
+ `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
+ assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
+ (off) irrespective of whether normal (`NDEBUG`-based) assertions are
+ enabled or not. A version of LLVM built with ABI breaking checks
+ is not ABI compatible with a version built without it.
-**LLVM_INCLUDE_TOOLS**:BOOL
- Generate build targets for the LLVM tools. Defaults to ON. You can use this
- option to disable the generation of build targets for the LLVM tools.
+**LLVM_APPEND_VC_REV**:BOOL
+ Embed version control revision info (Git revision id).
+ The version info is provided by the ``LLVM_REVISION`` macro in
+ ``llvm/include/llvm/Support/VCSRevision.h``. Developers using git who don't
+ need revision info can disable this option to avoid re-linking most binaries
+ after a branch switch. Defaults to ON.
-**LLVM_INSTALL_BINUTILS_SYMLINKS**:BOOL
- Install symlinks from the binutils tool names to the corresponding LLVM tools.
- For example, ar will be symlinked to llvm-ar.
+**LLVM_BUILD_32_BITS**:BOOL
+ Build 32-bit executables and libraries on 64-bit systems. This option is
+ available only on some 64-bit Unix systems. Defaults to OFF.
-**LLVM_INSTALL_CCTOOLS_SYMLINKS**:BOOL
- Install symliks from the cctools tool names to the corresponding LLVM tools.
- For example, lipo will be symlinked to llvm-lipo.
+**LLVM_BUILD_BENCHMARKS**:BOOL
+ Adds benchmarks to the list of default targets. Defaults to OFF.
+
+**LLVM_BUILD_DOCS**:BOOL
+ Adds all *enabled* documentation targets (i.e. Doxgyen and Sphinx targets) as
+ dependencies of the default build targets. This results in all of the (enabled)
+ documentation targets being as part of a normal build. If the ``install``
+ target is run then this also enables all built documentation targets to be
+ installed. Defaults to OFF. To enable a particular documentation target, see
+ see LLVM_ENABLE_SPHINX and LLVM_ENABLE_DOXYGEN.
**LLVM_BUILD_EXAMPLES**:BOOL
Build LLVM examples. Defaults to OFF. Targets for building each example are
generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
details.
-**LLVM_INCLUDE_EXAMPLES**:BOOL
- Generate build targets for the LLVM examples. Defaults to ON. You can use this
- option to disable the generation of build targets for the LLVM examples.
+**LLVM_BUILD_INSTRUMENTED_COVERAGE**:BOOL
+ If enabled, `source-based code coverage
+ <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation
+ is enabled while building llvm.
+
+**LLVM_BUILD_LLVM_DYLIB**:BOOL
+ If enabled, the target for building the libLLVM shared library is added.
+ This library contains all of LLVM's components in a single shared library.
+ Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS.
+ Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB
+ is also ON.
+ The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS
+ to a list of the desired components.
+ This option is not available on Windows.
**LLVM_BUILD_TESTS**:BOOL
Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
@@ -265,35 +289,86 @@ LLVM-specific variables
for a complete list of unit tests.) It is possible to build all unit tests
with the target *UnitTests*.
-**LLVM_INCLUDE_TESTS**:BOOL
- Generate build targets for the LLVM unit tests. Defaults to ON. You can use
- this option to disable the generation of build targets for the LLVM unit
- tests.
+**LLVM_BUILD_TOOLS**:BOOL
+ Build LLVM tools. Defaults to ON. Targets for building each tool are generated
+ in any case. You can build a tool separately by invoking its target. For
+ example, you can build *llvm-as* with a Makefile-based system by executing *make
+ llvm-as* at the root of your build directory.
-**LLVM_BUILD_BENCHMARKS**:BOOL
- Adds benchmarks to the list of default targets. Defaults to OFF.
+**LLVM_CCACHE_BUILD**:BOOL
+ If enabled and the ``ccache`` program is available, then LLVM will be
+ built using ``ccache`` to speed up rebuilds of LLVM and its components.
+ Defaults to OFF. The size and location of the cache maintained
+ by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
+ options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
+ variables, respectively.
-**LLVM_INCLUDE_BENCHMARKS**:BOOL
- Generate build targets for the LLVM benchmarks. Defaults to ON.
+**LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
+ macOS Only: If enabled CMake will generate a target named
+ 'install-xcode-toolchain'. This target will create a directory at
+ $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
+ be used to override the default system tools.
-**LLVM_APPEND_VC_REV**:BOOL
- Embed version control revision info (Git revision id).
- The version info is provided by the ``LLVM_REVISION`` macro in
- ``llvm/include/llvm/Support/VCSRevision.h``. Developers using git who don't
- need revision info can disable this option to avoid re-linking most binaries
- after a branch switch. Defaults to ON.
+**LLVM_DOXYGEN_QCH_FILENAME**:STRING
+ The filename of the Qt Compressed Help file that will be generated when
+ ``-DLLVM_ENABLE_DOXYGEN=ON`` and
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
+ ``org.llvm.qch``.
+ This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise it has no effect.
-**LLVM_ENABLE_THREADS**:BOOL
- Build with threads support, if available. Defaults to ON.
+**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
+ The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
+ ``find_program()`` can find. This option is only useful in combination with
+ ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
+ effect.
-**LLVM_ENABLE_UNWIND_TABLES**:BOOL
- Enable unwind tables in the binary. Disabling unwind tables can reduce the
- size of the libraries. Defaults to ON.
+**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
+ See `Qt Help Project`_ for
+ more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
+ is a combination of the package name and version string. This filter can then
+ be used in Qt Creator to select only documentation from LLVM when browsing
+ through all the help files that you might have loaded. This option is only
+ useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
+ otherwise it has no effect.
+
+.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
+ Namespace under which the intermediate Qt Help Project file lives. See `Qt
+ Help Project`_
+ for more information. Defaults to "org.llvm". This option is only useful in
+ combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
+ it has no effect.
+
+**LLVM_DOXYGEN_SVG**:BOOL
+ Uses .svg files instead of .png files for graphs in the Doxygen output.
+ Defaults to OFF.
**LLVM_ENABLE_ASSERTIONS**:BOOL
Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
is *Debug*.
+**LLVM_ENABLE_BINDINGS**:BOOL
+ If disabled, do not try to build the OCaml and go bindings.
+
+**LLVM_ENABLE_DIA_SDK**:BOOL
+ Enable building with MSVC DIA SDK for PDB debugging support. Available
+ only with MSVC. Defaults to ON.
+
+**LLVM_ENABLE_DOXYGEN**:BOOL
+ Enables the generation of browsable HTML documentation using doxygen.
+ Defaults to OFF.
+
+**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
+ Enables the generation of a Qt Compressed Help file. Defaults to OFF.
+ This affects the make target ``doxygen-llvm``. When enabled, apart from
+ the normal HTML output generated by doxygen, this will produce a QCH file
+ named ``org.llvm.qch``. You can then load this file into Qt Creator.
+ This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
+ otherwise this has no effect.
+
**LLVM_ENABLE_EH**:BOOL
Build LLVM with exception-handling support. This is necessary if you wish to
link against LLVM libraries and make use of C++ exceptions in your own code
@@ -302,6 +377,14 @@ LLVM-specific variables
**LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL
Enable additional time/memory expensive checking. Defaults to OFF.
+**LLVM_ENABLE_FFI**:BOOL
+ Indicates whether the LLVM Interpreter will be linked with the Foreign Function
+ Interface library (libffi) in order to enable calling external functions.
+ If the library or its headers are installed in a custom
+ location, you can also set the variables FFI_INCLUDE_DIR and
+ FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
+ respectively. Defaults to OFF.
+
**LLVM_ENABLE_IDE**:BOOL
Tell the build system that an IDE is being used. This in turn disables the
creation of certain convenience build system targets, such as the various
@@ -311,70 +394,81 @@ LLVM-specific variables
scenario where a manual override may be desirable is when using Visual Studio
2017's CMake integration, which would not be detected as an IDE otherwise.
+**LLVM_ENABLE_LIBCXX**:BOOL
+ If the host compiler and linker supports the stdlib flag, -stdlib=libc++ is
+ passed to invocations of both so that the project is built using libc++
+ instead of stdlibc++. Defaults to OFF.
+
+**LLVM_ENABLE_LIBPFM**:BOOL
+ Enable building with libpfm to support hardware counter measurements in LLVM
+ tools.
+ Defaults to ON.
+
+**LLVM_ENABLE_LLD**:BOOL
+ This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage
+ build where a dependency is added from the first stage to the second ensuring
+ that lld is built before stage2 begins.
+
+**LLVM_ENABLE_LTO**:STRING
+ Add ``-flto`` or ``-flto=`` flags to the compile and link command
+ lines, enabling link-time optimization. Possible values are ``Off``,
+ ``On``, ``Thin`` and ``Full``. Defaults to OFF.
+
**LLVM_ENABLE_MODULES**:BOOL
Compile with `Clang Header Modules
<https://clang.llvm.org/docs/Modules.html>`_.
+**LLVM_ENABLE_PEDANTIC**:BOOL
+ Enable pedantic mode. This disables compiler-specific extensions, if
+ possible. Defaults to ON.
+
**LLVM_ENABLE_PIC**:BOOL
Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
+**LLVM_ENABLE_PROJECTS**:STRING
+ Semicolon-separated list of projects to build, or *all* for building all
+ (clang, libcxx, libcxxabi, lldb, compiler-rt, lld, polly, etc) projects.
+ This flag assumes that projects are checked out side-by-side and not nested,
+ i.e. clang needs to be in parallel of llvm instead of nested in `llvm/tools`.
+ This feature allows to have one build for only LLVM and another for clang+llvm
+ using the same source checkout.
+ The full list is:
+ ``clang;clang-tools-extra;compiler-rt;debuginfo-tests;libc;libclc;libcxx;libcxxabi;libunwind;lld;lldb;openmp;parallel-libs;polly;pstl``
+
**LLVM_ENABLE_RTTI**:BOOL
Build LLVM with run-time type information. Defaults to OFF.
+**LLVM_ENABLE_SPHINX**:BOOL
+ If specified, CMake will search for the ``sphinx-build`` executable and will make
+ the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
+ Defaults to OFF.
+
+**LLVM_ENABLE_THREADS**:BOOL
+ Build with threads support, if available. Defaults to ON.
+
+**LLVM_ENABLE_UNWIND_TABLES**:BOOL
+ Enable unwind tables in the binary. Disabling unwind tables can reduce the
+ size of the libraries. Defaults to ON.
+
**LLVM_ENABLE_WARNINGS**:BOOL
Enable all compiler warnings. Defaults to ON.
-**LLVM_ENABLE_PEDANTIC**:BOOL
- Enable pedantic mode. This disables compiler-specific extensions, if
- possible. Defaults to ON.
-
**LLVM_ENABLE_WERROR**:BOOL
Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
-**LLVM_ABI_BREAKING_CHECKS**:STRING
- Used to decide if LLVM should be built with ABI breaking checks or
- not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
- `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
- assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
- (off) irrespective of whether normal (`NDEBUG`-based) assertions are
- enabled or not. A version of LLVM built with ABI breaking checks
- is not ABI compatible with a version built without it.
-
-**LLVM_BUILD_32_BITS**:BOOL
- Build 32-bit executables and libraries on 64-bit systems. This option is
- available only on some 64-bit Unix systems. Defaults to OFF.
+**LLVM_ENABLE_Z3_SOLVER**:BOOL
+ If enabled, the Z3 constraint solver is activated for the Clang static analyzer.
+ A recent version of the z3 library needs to be available on the system.
-**LLVM_TARGET_ARCH**:STRING
- LLVM target to use for native code generation. This is required for JIT
- generation. It defaults to "host", meaning that it shall pick the architecture
- of the machine where LLVM is being built. If you are cross-compiling, set it
- to the target architecture name.
+**LLVM_ENABLE_ZLIB**:BOOL
+ Enable building with zlib to support compression/uncompression in LLVM tools.
+ Defaults to ON.
-**LLVM_TABLEGEN**:STRING
- Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
- intended for cross-compiling: if the user sets this variable, no native
- TableGen will be created.
-
-**LLVM_LIT_ARGS**:STRING
- Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
- By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
- others.
-
-**LLVM_LIT_TOOLS_DIR**:PATH
- The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
- the empty string, in which case lit will look for tools needed for tests
- (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
- %PATH%, then you can set this variable to the GnuWin32 directory so that
- lit can find tools needed for tests in that directory.
-
-**LLVM_ENABLE_FFI**:BOOL
- Indicates whether the LLVM Interpreter will be linked with the Foreign Function
- Interface library (libffi) in order to enable calling external functions.
- If the library or its headers are installed in a custom
- location, you can also set the variables FFI_INCLUDE_DIR and
- FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
- respectively. Defaults to OFF.
+**LLVM_EXPERIMENTAL_TARGETS_TO_BUILD**:STRING
+ Semicolon-separated list of experimental targets to build and linked into
+ llvm. This will build the experimental target without needing it to add to the
+ list of all the targets available in the LLVM's main CMakeLists.txt.
**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
These variables specify the path to the source directory for the external
@@ -384,16 +478,6 @@ LLVM-specific variables
will not be used. If the variable for an external project does not point
to a valid path, then that project will not be built.
-**LLVM_ENABLE_PROJECTS**:STRING
- Semicolon-separated list of projects to build, or *all* for building all
- (clang, libcxx, libcxxabi, lldb, compiler-rt, lld, polly, etc) projects.
- This flag assumes that projects are checked out side-by-side and not nested,
- i.e. clang needs to be in parallel of llvm instead of nested in `llvm/tools`.
- This feature allows to have one build for only LLVM and another for clang+llvm
- using the same source checkout.
- The full list is:
- ``clang;clang-tools-extra;compiler-rt;debuginfo-tests;libc;libclc;libcxx;libcxxabi;libunwind;lld;lldb;openmp;parallel-libs;polly;pstl``
-
**LLVM_EXTERNAL_PROJECTS**:STRING
Semicolon-separated list of additional external projects to build as part of
llvm. For each project LLVM_EXTERNAL_<NAME>_SOURCE_DIR have to be specified
@@ -402,83 +486,52 @@ LLVM-specific variables
-DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
-DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.
-**LLVM_USE_OPROFILE**:BOOL
- Enable building OProfile JIT support. Defaults to OFF.
-
-**LLVM_PROFDATA_FILE**:PATH
- Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
- can only be specified if you're building with clang.
-
-**LLVM_USE_INTEL_JITEVENTS**:BOOL
- Enable building support for Intel JIT Events API. Defaults to OFF.
-
-**LLVM_ENABLE_LIBPFM**:BOOL
- Enable building with libpfm to support hardware counter measurements in LLVM
- tools.
- Defaults to ON.
-
-**LLVM_USE_PERF**:BOOL
- Enable building support for Perf (linux profiling tool) JIT support. Defaults to OFF.
-
-**LLVM_ENABLE_ZLIB**:BOOL
- Enable building with zlib to support compression/uncompression in LLVM tools.
- Defaults to ON.
-
-**LLVM_ENABLE_DIA_SDK**:BOOL
- Enable building with MSVC DIA SDK for PDB debugging support. Available
- only with MSVC. Defaults to ON.
-
-**LLVM_USE_SANITIZER**:STRING
- Define the sanitizer used to build LLVM binaries and tests. Possible values
- are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
- ``DataFlow``, and ``Address;Undefined``. Defaults to empty string.
+**LLVM_EXTERNALIZE_DEBUGINFO**:BOOL
+ Generate dSYM files and strip executables and libraries (Darwin Only).
+ Defaults to OFF.
-**LLVM_UBSAN_FLAGS**:STRING
- Defines the set of compile flags used to enable UBSan. Only used if
- ``LLVM_USE_SANITIZER`` contains ``Undefined``. This can be used to override
- the default set of UBSan flags.
+**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
+ If enabled, the compiler and standard library versions won't be checked. LLVM
+ may not compile at all, or might fail at runtime due to known bugs in these
+ toolchains.
-**LLVM_ENABLE_LTO**:STRING
- Add ``-flto`` or ``-flto=`` flags to the compile and link command
- lines, enabling link-time optimization. Possible values are ``Off``,
- ``On``, ``Thin`` and ``Full``. Defaults to OFF.
+**LLVM_INCLUDE_BENCHMARKS**:BOOL
+ Generate build targets for the LLVM benchmarks. Defaults to ON.
-**LLVM_USE_LINKER**:STRING
- Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on
- your compiler, for clang the value can be an absolute path to your custom
- linker, otherwise clang will prefix the name with ``ld.`` and apply its usual
- search. For example to link LLVM with the Gold linker, cmake can be invoked
- with ``-DLLVM_USE_LINKER=gold``.
+**LLVM_INCLUDE_EXAMPLES**:BOOL
+ Generate build targets for the LLVM examples. Defaults to ON. You can use this
+ option to disable the generation of build targets for the LLVM examples.
-**LLVM_ENABLE_LIBCXX**:BOOL
- If the host compiler and linker supports the stdlib flag, -stdlib=libc++ is
- passed to invocations of both so that the project is built using libc++
- instead of stdlibc++. Defaults to OFF.
+**LLVM_INCLUDE_TESTS**:BOOL
+ Generate build targets for the LLVM unit tests. Defaults to ON. You can use
+ this option to disable the generation of build targets for the LLVM unit
+ tests.
-**LLVM_STATIC_LINK_CXX_STDLIB**:BOOL
- Statically link to the C++ standard library if possible. This uses the flag
- "-static-libstdc++", but a Clang host compiler will statically link to libc++
- if used in conjunction with the **LLVM_ENABLE_LIBCXX** flag. Defaults to OFF.
+**LLVM_INCLUDE_TOOLS**:BOOL
+ Generate build targets for the LLVM tools. Defaults to ON. You can use this
+ option to disable the generation of build targets for the LLVM tools.
-**LLVM_ENABLE_LLD**:BOOL
- This option is equivalent to `-DLLVM_USE_LINKER=lld`, except during a 2-stage
- build where a dependency is added from the first stage to the second ensuring
- that lld is built before stage2 begins.
+**LLVM_INSTALL_BINUTILS_SYMLINKS**:BOOL
+ Install symlinks from the binutils tool names to the corresponding LLVM tools.
+ For example, ar will be symlinked to llvm-ar.
-**LLVM_PARALLEL_COMPILE_JOBS**:STRING
- Define the maximum number of concurrent compilation jobs.
+**LLVM_INSTALL_CCTOOLS_SYMLINKS**:BOOL
+ Install symliks from the cctools tool names to the corresponding LLVM tools.
+ For example, lipo will be symlinked to llvm-lipo.
-**LLVM_PARALLEL_LINK_JOBS**:STRING
- Define the maximum number of concurrent link jobs.
+**LLVM_INSTALL_OCAMLDOC_HTML_DIR**:STRING
+ The path to install OCamldoc-generated HTML documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm/ocaml-html`.
-**LLVM_EXTERNALIZE_DEBUGINFO**:BOOL
- Generate dSYM files and strip executables and libraries (Darwin Only).
- Defaults to OFF.
+**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING
+ The path to install Sphinx-generated HTML documentation to. This path can
+ either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+ `share/doc/llvm/html`.
-**LLVM_USE_CRT_{target}**:STRING
- On Windows, tells which version of the C runtime library (CRT) should be used.
- For example, -DLLVM_USE_CRT_RELEASE=MT would statically link the CRT into the
- LLVM tools and library.
+**LLVM_INSTALL_UTILS**:BOOL
+ If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed
+ to CMAKE_INSTALL_PREFIX.
**LLVM_INTEGRATED_CRT_ALLOC**:PATH
On Windows, allows embedding a
diff erent C runtime allocator into the LLVM
@@ -496,136 +549,28 @@ LLVM-specific variables
This flag needs to be used along with the static CRT, ie. if building the
Release target, add -DLLVM_USE_CRT_RELEASE=MT.
-**LLVM_BUILD_DOCS**:BOOL
- Adds all *enabled* documentation targets (i.e. Doxgyen and Sphinx targets) as
- dependencies of the default build targets. This results in all of the (enabled)
- documentation targets being as part of a normal build. If the ``install``
- target is run then this also enables all built documentation targets to be
- installed. Defaults to OFF. To enable a particular documentation target, see
- see LLVM_ENABLE_SPHINX and LLVM_ENABLE_DOXYGEN.
-
-**LLVM_ENABLE_DOXYGEN**:BOOL
- Enables the generation of browsable HTML documentation using doxygen.
- Defaults to OFF.
-
-**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
- Enables the generation of a Qt Compressed Help file. Defaults to OFF.
- This affects the make target ``doxygen-llvm``. When enabled, apart from
- the normal HTML output generated by doxygen, this will produce a QCH file
- named ``org.llvm.qch``. You can then load this file into Qt Creator.
- This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
- otherwise this has no effect.
-
-**LLVM_DOXYGEN_QCH_FILENAME**:STRING
- The filename of the Qt Compressed Help file that will be generated when
- ``-DLLVM_ENABLE_DOXYGEN=ON`` and
- ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
- ``org.llvm.qch``.
- This option is only useful in combination with
- ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
- otherwise it has no effect.
-
-**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
- Namespace under which the intermediate Qt Help Project file lives. See `Qt
- Help Project`_
- for more information. Defaults to "org.llvm". This option is only useful in
- combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
- it has no effect.
-
-**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
- See `Qt Help Project`_ for
- more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
- is a combination of the package name and version string. This filter can then
- be used in Qt Creator to select only documentation from LLVM when browsing
- through all the help files that you might have loaded. This option is only
- useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
- otherwise it has no effect.
-
-.. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
-
-**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
- The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
- ``find_program()`` can find. This option is only useful in combination with
- ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
- effect.
-
-**LLVM_DOXYGEN_SVG**:BOOL
- Uses .svg files instead of .png files for graphs in the Doxygen output.
- Defaults to OFF.
-
**LLVM_INSTALL_DOXYGEN_HTML_DIR**:STRING
The path to install Doxygen-generated HTML documentation to. This path can
either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
`share/doc/llvm/doxygen-html`.
-**LLVM_ENABLE_SPHINX**:BOOL
- If specified, CMake will search for the ``sphinx-build`` executable and will make
- the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
- Defaults to OFF.
-
-**SPHINX_EXECUTABLE**:STRING
- The path to the ``sphinx-build`` executable detected by CMake.
- For installation instructions, see
- https://www.sphinx-doc.org/en/master/usage/installation.html
-
-**SPHINX_OUTPUT_HTML**:BOOL
- If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
- building the documentation as html are added (but not built by default unless
- ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
- source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
- and ``docs-lld-html``). Defaults to ON.
-
-**SPHINX_OUTPUT_MAN**:BOOL
- If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
- the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
- is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
- to ON.
-
-**SPHINX_WARNINGS_AS_ERRORS**:BOOL
- If enabled then sphinx documentation warnings will be treated as
- errors. Defaults to ON.
-
-**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING
- The path to install Sphinx-generated HTML documentation to. This path can
- either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
- `share/doc/llvm/html`.
-
-**LLVM_INSTALL_OCAMLDOC_HTML_DIR**:STRING
- The path to install OCamldoc-generated HTML documentation to. This path can
- either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
- `share/doc/llvm/ocaml-html`.
-
-**LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
- macOS Only: If enabled CMake will generate a target named
- 'install-xcode-toolchain'. This target will create a directory at
- $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
- be used to override the default system tools.
-
-**LLVM_BUILD_LLVM_DYLIB**:BOOL
- If enabled, the target for building the libLLVM shared library is added.
- This library contains all of LLVM's components in a single shared library.
- Defaults to OFF. This cannot be used in conjunction with BUILD_SHARED_LIBS.
- Tools will only be linked to the libLLVM shared library if LLVM_LINK_LLVM_DYLIB
- is also ON.
- The components in the library can be customised by setting LLVM_DYLIB_COMPONENTS
- to a list of the desired components.
- This option is not available on Windows.
-
**LLVM_LINK_LLVM_DYLIB**:BOOL
If enabled, tools will be linked with the libLLVM shared library. Defaults
to OFF. Setting LLVM_LINK_LLVM_DYLIB to ON also sets LLVM_BUILD_LLVM_DYLIB
to ON.
This option is not available on Windows.
-**BUILD_SHARED_LIBS**:BOOL
- Flag indicating if each LLVM component (e.g. Support) is built as a shared
- library (ON) or as a static library (OFF). Its default value is OFF. On
- Windows, shared libraries may be used when building with MinGW, including
- mingw-w64, but not when building with the Microsoft toolchain.
+**LLVM_LIT_ARGS**:STRING
+ Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
+ By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
+ others.
- .. note:: BUILD_SHARED_LIBS is only recommended for use by LLVM developers.
- If you want to build LLVM as a shared library, you should use the
- ``LLVM_BUILD_LLVM_DYLIB`` option.
+**LLVM_LIT_TOOLS_DIR**:PATH
+ The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
+ the empty string, in which case lit will look for tools needed for tests
+ (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
+ %PATH%, then you can set this variable to the GnuWin32 directory so that
+ lit can find tools needed for tests in that directory.
**LLVM_OPTIMIZED_TABLEGEN**:BOOL
If enabled and building a debug or asserts build the CMake build system will
@@ -633,54 +578,109 @@ LLVM-specific variables
during the build. Enabling this option can significantly speed up build times
especially when building LLVM in Debug configurations.
+**LLVM_PARALLEL_COMPILE_JOBS**:STRING
+ Define the maximum number of concurrent compilation jobs.
+
+**LLVM_PARALLEL_LINK_JOBS**:STRING
+ Define the maximum number of concurrent link jobs.
+
+**LLVM_PROFDATA_FILE**:PATH
+ Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
+ can only be specified if you're building with clang.
+
**LLVM_REVERSE_ITERATION**:BOOL
If enabled, all supported unordered llvm containers would be iterated in
reverse order. This is useful for uncovering non-determinism caused by
iteration of unordered containers.
-**LLVM_BUILD_INSTRUMENTED_COVERAGE**:BOOL
- If enabled, `source-based code coverage
- <https://clang.llvm.org/docs/SourceBasedCodeCoverage.html>`_ instrumentation
- is enabled while building llvm.
+**LLVM_STATIC_LINK_CXX_STDLIB**:BOOL
+ Statically link to the C++ standard library if possible. This uses the flag
+ "-static-libstdc++", but a Clang host compiler will statically link to libc++
+ if used in conjunction with the **LLVM_ENABLE_LIBCXX** flag. Defaults to OFF.
-**LLVM_CCACHE_BUILD**:BOOL
- If enabled and the ``ccache`` program is available, then LLVM will be
- built using ``ccache`` to speed up rebuilds of LLVM and its components.
- Defaults to OFF. The size and location of the cache maintained
- by ``ccache`` can be adjusted via the LLVM_CCACHE_MAXSIZE and LLVM_CCACHE_DIR
- options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
- variables, respectively.
+**LLVM_TABLEGEN**:STRING
+ Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
+ intended for cross-compiling: if the user sets this variable, no native
+ TableGen will be created.
-**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
- If enabled, the compiler and standard library versions won't be checked. LLVM
- may not compile at all, or might fail at runtime due to known bugs in these
- toolchains.
+**LLVM_TARGET_ARCH**:STRING
+ LLVM target to use for native code generation. This is required for JIT
+ generation. It defaults to "host", meaning that it shall pick the architecture
+ of the machine where LLVM is being built. If you are cross-compiling, set it
+ to the target architecture name.
+
+**LLVM_TARGETS_TO_BUILD**:STRING
+ Semicolon-separated list of targets to build, or *all* for building all
+ targets. Case-sensitive. Defaults to *all*. Example:
+ ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL
If enabled, the compiler version check will only warn when using a toolchain
which is about to be deprecated, instead of emitting an error.
+**LLVM_UBSAN_FLAGS**:STRING
+ Defines the set of compile flags used to enable UBSan. Only used if
+ ``LLVM_USE_SANITIZER`` contains ``Undefined``. This can be used to override
+ the default set of UBSan flags.
+
+**LLVM_USE_CRT_{target}**:STRING
+ On Windows, tells which version of the C runtime library (CRT) should be used.
+ For example, -DLLVM_USE_CRT_RELEASE=MT would statically link the CRT into the
+ LLVM tools and library.
+
+**LLVM_USE_INTEL_JITEVENTS**:BOOL
+ Enable building support for Intel JIT Events API. Defaults to OFF.
+
+**LLVM_USE_LINKER**:STRING
+ Add ``-fuse-ld={name}`` to the link invocation. The possible value depend on
+ your compiler, for clang the value can be an absolute path to your custom
+ linker, otherwise clang will prefix the name with ``ld.`` and apply its usual
+ search. For example to link LLVM with the Gold linker, cmake can be invoked
+ with ``-DLLVM_USE_LINKER=gold``.
+
**LLVM_USE_NEWPM**:BOOL
If enabled, use the experimental new pass manager.
-**LLVM_ENABLE_BINDINGS**:BOOL
- If disabled, do not try to build the OCaml and go bindings.
+**LLVM_USE_OPROFILE**:BOOL
+ Enable building OProfile JIT support. Defaults to OFF.
-**LLVM_ENABLE_Z3_SOLVER**:BOOL
- If enabled, the Z3 constraint solver is activated for the Clang static analyzer.
- A recent version of the z3 library needs to be available on the system.
+**LLVM_USE_PERF**:BOOL
+ Enable building support for Perf (linux profiling tool) JIT support. Defaults to OFF.
+
+**LLVM_USE_RELATIVE_PATHS_IN_FILES**:BOOL
+ Rewrite absolute source paths in sources and debug info to relative ones. The
+ source prefix can be adjusted via the LLVM_SOURCE_PREFIX variable.
**LLVM_USE_RELATIVE_PATHS_IN_DEBUG_INFO**:BOOL
Rewrite absolute source paths in debug info to relative ones. The source prefix
can be adjusted via the LLVM_SOURCE_PREFIX variable.
-**LLVM_USE_RELATIVE_PATHS_IN_FILES**:BOOL
- Rewrite absolute source paths in sources and debug info to relative ones. The
- source prefix can be adjusted via the LLVM_SOURCE_PREFIX variable.
+**LLVM_USE_SANITIZER**:STRING
+ Define the sanitizer used to build LLVM binaries and tests. Possible values
+ are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
+ ``DataFlow``, and ``Address;Undefined``. Defaults to empty string.
-**LLVM_INSTALL_UTILS**:BOOL
- If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed
- to CMAKE_INSTALL_PREFIX.
+**SPHINX_EXECUTABLE**:STRING
+ The path to the ``sphinx-build`` executable detected by CMake.
+ For installation instructions, see
+ https://www.sphinx-doc.org/en/master/usage/installation.html
+
+**SPHINX_OUTPUT_HTML**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) then the targets for
+ building the documentation as html are added (but not built by default unless
+ ``LLVM_BUILD_DOCS`` is enabled). There is a target for each project in the
+ source tree that uses sphinx (e.g. ``docs-llvm-html``, ``docs-clang-html``
+ and ``docs-lld-html``). Defaults to ON.
+
+**SPHINX_OUTPUT_MAN**:BOOL
+ If enabled (and ``LLVM_ENABLE_SPHINX`` is enabled) the targets for building
+ the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
+ is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
+ to ON.
+
+**SPHINX_WARNINGS_AS_ERRORS**:BOOL
+ If enabled then sphinx documentation warnings will be treated as
+ errors. Defaults to ON.
CMake Caches
============
More information about the llvm-commits
mailing list