Dan Liew
0d8316a53d
This change introduces a new CMake cache variable `COMPILER_RT_ENABLE_TEST_SUITES` that allows users to have fine-grained control over which test suites are included and therefore run when running `ninja check-all`. For example building with `COMPILER_RT_ENABLE_TEST_SUITES=builtins;asan` will only enable the builtins and asan tests under `compiler-rt/tests`. The default value of `COMPILER_RT_INCLUDE_TESTS` is `all` which is a special value that includes everything and it being the default means this patch preserves existing behavior. Note this new option only has affect when `COMPILER_RT_INCLUDE_TESTS` is On. The primary use case for this change is it allows controlling tests that don't have a corresponding runtime to be enabled/disabled. An example of this is the `shadowcallstack` test suite. `-fbounds-safety` also has a downstream test suite in compiler-rt like this. Previously there was no way to disable including these tests when `COMPILER_RT_INCLUDE_TESTS` was on. The `-fbounds-safety` test suite will be upstreamed once the necessary clang pieces exist upstream. A side benefit of this change is it allows building runtimes but not testing some of them which can be useful in some testing environments (e.g. smoke-test). It is not the primary motivation though. While the existing `COMPILER_RT_BUILD_<NAME>` options can be used to prevent running tests (by not building corresponding runtimes) that isn't a good solution because it: * Doesn't work for tests that have no corresponding runtime to be built like `shadowcallstack` because there's no CMake option for it. * Requires specifying multiple CMake options to disable building each runtime that we don't want tested. This approach disallows "building but not testing certain runtimes" and also is annoying to maintain because its effectively a subtractive list (you say what you don't want) that has to be updated everytime a new runtime is introduced whereas COMPILER_RT_ENABLE_TEST_SUITES is an additive list (you say what you want) that doesn't need modifying everytime a new runtime is introduced. To implement this all test directories in `compiler-rt/test` are now added through the `compiler_rt_test_runtime()` function which has been adapted to accommodate all use cases. Assisted-by: Claude Code rdar://176477660
108 lines
3.3 KiB
ReStructuredText
108 lines
3.3 KiB
ReStructuredText
.. _BuildingCompilerRT:
|
|
|
|
===============
|
|
Building Compiler-RT
|
|
===============
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. _build instructions:
|
|
|
|
The instructions on this page are aimed at vendors who ship Compiler-RT as part of an
|
|
operating system distribution, a toolchain or similar shipping vehicles. If you
|
|
are a user merely trying to use Compiler-RT in your program, you most likely want to
|
|
refer to your vendor's documentation, or to the general documentation for using
|
|
LLVM, Clang, the various santizers, etc.
|
|
|
|
CMake Options
|
|
=============
|
|
|
|
Here are some of the CMake variables that are used often, along with a
|
|
brief explanation and LLVM-specific notes. For full documentation, check the
|
|
CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
|
|
|
|
**CMAKE_BUILD_TYPE**:STRING
|
|
Sets the build type for ``make`` based generators. Possible values are
|
|
Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio
|
|
the user sets the build type with the IDE settings.
|
|
|
|
**CMAKE_INSTALL_PREFIX**:PATH
|
|
Path where LLVM will be installed if "make install" is invoked or the
|
|
"INSTALL" target is built.
|
|
|
|
**CMAKE_CXX_COMPILER**:STRING
|
|
The C++ compiler to use when building and testing Compiler-RT.
|
|
|
|
|
|
.. _compiler-rt-specific options:
|
|
|
|
Compiler-RT specific options
|
|
-----------------------
|
|
|
|
.. option:: COMPILER_RT_INSTALL_PATH:PATH
|
|
|
|
**Default**: ```` (empty relative path)
|
|
|
|
Prefix for directories where built Compiler-RT artifacts should be installed.
|
|
Can be an absolute path, like the default empty string, in which case it is
|
|
relative ``CMAKE_INSTALL_PREFIX``. If setting a relative path, make sure to
|
|
include the ``:PATH`` with your ``-D``, i.e. use
|
|
``-DCOMPILER_RT_INSTALL_PATH:PATH=...`` not
|
|
``-DCOMPILER_RT_INSTALL_PATH=...``, otherwise CMake will convert the
|
|
path to an absolute path.
|
|
|
|
.. option:: COMPILER_RT_INSTALL_LIBRARY_DIR:PATH
|
|
|
|
**Default**: ``lib``
|
|
|
|
Path where built Compiler-RT libraries should be installed. If a relative
|
|
path, relative to ``COMPILER_RT_INSTALL_PATH``.
|
|
|
|
.. option:: COMPILER_RT_INSTALL_BINARY_DIR:PATH
|
|
|
|
**Default**: ``bin``
|
|
|
|
Path where built Compiler-RT executables should be installed. If a relative
|
|
path, relative to ``COMPILER_RT_INSTALL_PATH``.
|
|
|
|
.. option:: COMPILER_RT_INSTALL_INCLUDE_DIR:PATH
|
|
|
|
**Default**: ``include``
|
|
|
|
Path where Compiler-RT headers should be installed. If a relative
|
|
path, relative to ``COMPILER_RT_INSTALL_PATH``.
|
|
|
|
.. option:: COMPILER_RT_INSTALL_DATA_DIR:PATH
|
|
|
|
**Default**: ``share``
|
|
|
|
Path where Compiler-RT data should be installed. If a relative
|
|
path, relative to ``COMPILER_RT_INSTALL_PATH``.
|
|
|
|
.. option:: COMPILER_RT_INCLUDE_TESTS:BOOL
|
|
|
|
**Default**: ``LLVM_INCLUDE_TESTS`` in LLVM builds, ``OFF`` in standalone builds.
|
|
|
|
Generate and build compiler-rt tests. If ``OFF``,
|
|
``COMPILER_RT_ENABLE_TEST_SUITES`` has no effect.
|
|
|
|
.. option:: COMPILER_RT_ENABLE_TEST_SUITES:STRING
|
|
|
|
**Default**: ``all``
|
|
|
|
Semicolon-separated list of test suites to enable, or ``all`` to enable all
|
|
test suites.
|
|
Example: ``-DCOMPILER_RT_ENABLE_TEST_SUITES="asan;ubsan;lsan"``
|
|
|
|
.. _LLVM-specific variables:
|
|
|
|
LLVM-specific options
|
|
---------------------
|
|
|
|
.. option:: 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``.
|