Skip to content

Commit

Permalink
[llvm][docs] Resort cmake macros (#87551)
Browse files Browse the repository at this point in the history
The cmake macro documentation had once again become unsorted. For names
of the form 'PREFIX_{list-or-category}_SUFFIX' I collate as 'PREFIX_SUFFIX'.
  • Loading branch information
urnathan committed Apr 8, 2024
1 parent 4308c74 commit f6357bb
Showing 1 changed file with 68 additions and 69 deletions.
137 changes: 68 additions & 69 deletions llvm/docs/CMake.rst
Original file line number Diff line number Diff line change
Expand Up @@ -283,14 +283,14 @@ manual, or execute ``cmake --help-variable VARIABLE_NAME``.
The path to install executables, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to "bin".

**CMAKE_INSTALL_INCLUDEDIR**:PATH
The path to install header files, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to "include".

**CMAKE_INSTALL_DOCDIR**:PATH
The path to install documentation, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to "share/doc".

**CMAKE_INSTALL_INCLUDEDIR**:PATH
The path to install header files, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to "include".

**CMAKE_INSTALL_MANDIR**:PATH
The path to install manpage files, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to "share/man".
Expand Down Expand Up @@ -328,28 +328,22 @@ enabled sub-projects. Nearly all of these variable names begin with
allows for them to be specified as values in CMAKE_BUILD_TYPE without
encountering a fatal error during the configuration process.

**LLVM_UNREACHABLE_OPTIMIZE**:BOOL
This flag controls the behavior of `llvm_unreachable()` in release build
(when assertions are disabled in general). When ON (default) then
`llvm_unreachable()` is considered "undefined behavior" and optimized as
such. When OFF it is instead replaced with a guaranteed "trap".

**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_FORCE_VC_REPOSITORY**:STRING
Set the git repository to include in version info rather than calling git to
determine it.

**LLVM_FORCE_VC_REVISION**:STRING
Force a specific Git revision id rather than calling to git to determine it.
This is useful in environments where git is not available or non-functional
but the VC revision is available through other means.

**LLVM_FORCE_VC_REPOSITORY**:STRING
Set the git repository to include in version info rather than calling git to
determine 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.
Expand Down Expand Up @@ -381,22 +375,6 @@ enabled sub-projects. Nearly all of these variable names begin with
*LLVM_CODE_COVERAGE_TARGETS* and *LLVM_COVERAGE_SOURCE_DIRS* for more
information on configuring code coverage reports.

**LLVM_CODE_COVERAGE_TARGETS**:STRING
If set to a semicolon separated list of targets, those targets will be used
to drive the code coverage reports. If unset, the target list will be
constructed using the LLVM build's CMake export list.

**LLVM_COVERAGE_SOURCE_DIRS**:STRING
If set to a semicolon separated list of directories, the coverage reports
will limit code coverage summaries to just the listed directories. If unset,
coverage reports will include all sources identified by the tooling.

**LLVM_INDIVIDUAL_TEST_COVERAGE**:BOOL
Enable individual test case coverage. When set to ON, code coverage data for
each test case will be generated and stored in a separate directory under the
config.test_exec_root path. This feature allows code coverage analysis of each
individual test case. Defaults to OFF.

**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.
Expand Down Expand Up @@ -429,15 +407,22 @@ enabled sub-projects. Nearly all of these variable names begin with
options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
variables, respectively.

**LLVM_CODE_COVERAGE_TARGETS**:STRING
If set to a semicolon separated list of targets, those targets will be used
to drive the code coverage reports. If unset, the target list will be
constructed using the LLVM build's CMake export list.

**LLVM_COVERAGE_SOURCE_DIRS**:STRING
If set to a semicolon separated list of directories, the coverage reports
will limit code coverage summaries to just the listed directories. If unset,
coverage reports will include all sources identified by the tooling.

**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_<target>_LINKER_FLAGS**:STRING
Defines the set of linker flags that should be applied to a <target>.

**LLVM_DEFAULT_TARGET_TRIPLE**:STRING
LLVM target to use for code generation when no target is explicitly specified.
It defaults to "host", meaning that it shall pick the architecture
Expand Down Expand Up @@ -514,11 +499,6 @@ enabled sub-projects. Nearly all of these variable names begin with
**LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL
Enable additional time/memory expensive checking. Defaults to OFF.

**LLVM_ENABLE_HTTPLIB**:BOOL
Enables the optional cpp-httplib dependency which is used by llvm-debuginfod
to serve debug info over HTTP. `cpp-httplib <https://github.com/yhirose/cpp-httplib>`_
must be installed, or `httplib_ROOT` must be set. 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.
Expand All @@ -527,6 +507,11 @@ enabled sub-projects. Nearly all of these variable names begin with
FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
respectively. Defaults to OFF.

**LLVM_ENABLE_HTTPLIB**:BOOL
Enables the optional cpp-httplib dependency which is used by llvm-debuginfod
to serve debug info over HTTP. `cpp-httplib <https://github.com/yhirose/cpp-httplib>`_
must be installed, or `httplib_ROOT` must be set. 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
Expand All @@ -539,11 +524,6 @@ enabled sub-projects. Nearly all of these variable names begin with
passed to invocations of both so that the project is built using libc++
instead of stdlibc++. Defaults to OFF.

**LLVM_ENABLE_LLVM_LIBC**: BOOL
If the LLVM libc overlay is installed in a location where the host linker
can access it, all built executables will be linked against the LLVM libc
overlay before linking against the system libc. Defaults to OFF.

**LLVM_ENABLE_LIBPFM**:BOOL
Enable building with libpfm to support hardware counter measurements in LLVM
tools.
Expand All @@ -554,6 +534,11 @@ enabled sub-projects. Nearly all of these variable names begin with
build where a dependency is added from the first stage to the second ensuring
that lld is built before stage2 begins.

**LLVM_ENABLE_LLVM_LIBC**: BOOL
If the LLVM libc overlay is installed in a location where the host linker
can access it, all built executables will be linked against the LLVM libc
overlay before linking against the system libc. Defaults to OFF.

**LLVM_ENABLE_LTO**:STRING
Add ``-flto`` or ``-flto=`` flags to the compile and link command
lines, enabling link-time optimization. Possible values are ``Off``,
Expand Down Expand Up @@ -581,6 +566,9 @@ enabled sub-projects. Nearly all of these variable names begin with
The full list is:
``clang;clang-tools-extra;cross-project-tests;libc;libclc;lld;lldb;openmp;polly;pstl``

**LLVM_ENABLE_RTTI**:BOOL
Build LLVM with run-time type information. Defaults to OFF.

**LLVM_ENABLE_RUNTIMES**:STRING
Build libc++, libc++abi, libunwind or compiler-rt using the just-built compiler.
This is the correct way to build runtimes when putting together a toolchain.
Expand All @@ -593,10 +581,6 @@ enabled sub-projects. Nearly all of these variable names begin with
To enable all of them, use:
``LLVM_ENABLE_RUNTIMES=all``


**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.
Expand Down Expand Up @@ -634,14 +618,6 @@ enabled sub-projects. Nearly all of these variable names begin with
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
LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
source directory. If the in-tree subdirectory for an external project
exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
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_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
Expand All @@ -650,6 +626,14 @@ enabled sub-projects. Nearly all of these variable names begin with
-DLLVM_EXTERNAL_FOO_SOURCE_DIR=/src/foo
-DLLVM_EXTERNAL_BAR_SOURCE_DIR=/src/bar``.

**LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
These variables specify the path to the source directory for the external
LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
source directory. If the in-tree subdirectory for an external project
exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
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_EXTERNALIZE_DEBUGINFO**:BOOL
Generate dSYM files and strip executables and libraries (Darwin Only).
Defaults to OFF.
Expand Down Expand Up @@ -680,6 +664,12 @@ enabled sub-projects. Nearly all of these variable names begin with
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_INDIVIDUAL_TEST_COVERAGE**:BOOL
Enable individual test case coverage. When set to ON, code coverage data for
each test case will be generated and stored in a separate directory under the
config.test_exec_root path. This feature allows code coverage analysis of each
individual test case. Defaults to OFF.

**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.
Expand All @@ -702,6 +692,11 @@ enabled sub-projects. Nearly all of these variable names begin with
If enabled, utility binaries like ``FileCheck`` and ``not`` will be installed
to CMAKE_INSTALL_PREFIX.

**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
``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``.

**LLVM_INTEGRATED_CRT_ALLOC**:PATH
On Windows, allows embedding a different C runtime allocator into the LLVM
tools and libraries. Using a lock-free allocator such as the ones listed below
Expand All @@ -718,17 +713,15 @@ enabled sub-projects. Nearly all of these variable names begin with
This flag needs to be used along with the static CRT, ie. if building the
Release target, add -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded.

**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
``${CMAKE_INSTALL_DOCDIR}/llvm/doxygen-html``.

**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.

**LLVM_<target>_LINKER_FLAGS**:STRING
Defines the set of linker flags that should be applied to a <target>.

**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
Expand Down Expand Up @@ -770,6 +763,10 @@ enabled sub-projects. Nearly all of these variable names begin with
**LLVM_PARALLEL_TABLEGEN_JOBS**:STRING
Define the maximum number of concurrent tablegen 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_RAM_PER_COMPILE_JOB**:STRING
Calculates the amount of Ninja compile jobs according to available resources.
Value has to be in MB, overwrites LLVM_PARALLEL_COMPILE_JOBS. Compile jobs
Expand All @@ -788,10 +785,6 @@ enabled sub-projects. Nearly all of these variable names begin with
Value has to be in MB, overwrites LLVM_PARALLEL_TABLEGEN_JOBS. Tablegen jobs
will be between one and amount of logical cores.

**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
Expand Down Expand Up @@ -829,6 +822,12 @@ enabled sub-projects. Nearly all of these variable names begin with
``LLVM_USE_SANITIZER`` contains ``Undefined``. This can be used to override
the default set of UBSan flags.

**LLVM_UNREACHABLE_OPTIMIZE**:BOOL
This flag controls the behavior of `llvm_unreachable()` in release build
(when assertions are disabled in general). When ON (default) then
`llvm_unreachable()` is considered "undefined behavior" and optimized as
such. When OFF it is instead replaced with a guaranteed "trap".

**LLVM_USE_INTEL_JITEVENTS**:BOOL
Enable building support for Intel JIT Events API. Defaults to OFF.

Expand Down Expand Up @@ -892,6 +891,11 @@ Advanced variables
These are niche, and changing them from their defaults is more likely to cause
things to go wrong. They are also unstable across LLVM versions.

**LLVM_EXAMPLES_INSTALL_DIR**:STRING
The path for examples of using LLVM, relative to the *CMAKE_INSTALL_PREFIX*.
Only matters if *LLVM_BUILD_EXAMPLES* is enabled.
Defaults to "examples".

**LLVM_TOOLS_INSTALL_DIR**:STRING
The path to install the main LLVM tools, relative to the *CMAKE_INSTALL_PREFIX*.
Defaults to *CMAKE_INSTALL_BINDIR*.
Expand All @@ -901,11 +905,6 @@ things to go wrong. They are also unstable across LLVM versions.
Only matters if *LLVM_INSTALL_UTILS* is enabled.
Defaults to *LLVM_TOOLS_INSTALL_DIR*.

**LLVM_EXAMPLES_INSTALL_DIR**:STRING
The path for examples of using LLVM, relative to the *CMAKE_INSTALL_PREFIX*.
Only matters if *LLVM_BUILD_EXAMPLES* is enabled.
Defaults to "examples".

CMake Caches
============

Expand Down

0 comments on commit f6357bb

Please sign in to comment.