[llvm] f6357bb - [llvm][docs] Resort cmake macros (#87551)
via llvm-commits
llvm-commits at lists.llvm.org
Mon Apr 8 06:02:14 PDT 2024
Author: Nathan Sidwell
Date: 2024-04-08T09:02:10-04:00
New Revision: f6357bb4283e72d1248b9c7eb67d98bea71d5f50
URL: https://github.com/llvm/llvm-project/commit/f6357bb4283e72d1248b9c7eb67d98bea71d5f50
DIFF: https://github.com/llvm/llvm-project/commit/f6357bb4283e72d1248b9c7eb67d98bea71d5f50.diff
LOG: [llvm][docs] Resort cmake macros (#87551)
The cmake macro documentation had once again become unsorted. For names
of the form 'PREFIX_{list-or-category}_SUFFIX' I collate as 'PREFIX_SUFFIX'.
Added:
Modified:
llvm/docs/CMake.rst
Removed:
################################################################################
diff --git a/llvm/docs/CMake.rst b/llvm/docs/CMake.rst
index 7a809d44d3d819..f7f8ed2e1a8528 100644
--- a/llvm/docs/CMake.rst
+++ b/llvm/docs/CMake.rst
@@ -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".
@@ -328,12 +328,6 @@ 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
@@ -341,15 +335,15 @@ enabled sub-projects. Nearly all of these variable names begin with
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.
@@ -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.
@@ -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
@@ -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.
@@ -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
@@ -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.
@@ -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``,
@@ -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.
@@ -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.
@@ -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
@@ -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.
@@ -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.
@@ -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
diff erent C runtime allocator into the LLVM
tools and libraries. Using a lock-free allocator such as the ones listed below
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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*.
@@ -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
============
More information about the llvm-commits
mailing list