This page describes how to build TFEL/MFront with
sanitizers and how to run the tests of the build tree with them. The
available cmake options are described in the installation
documentation.
A sanitizer is enabled either by listing it in the
enable-sanitize-options option or by enabling its dedicated
option, enable-<name>-sanitizer:
$ cmake <srcdir> -B build -DCMAKE_BUILD_TYPE=Debug \
-Denable-sanitize-options="address;undefined"As for any cmake list, the sanitizer names are separated
by semicolons, which shall be quoted not to be interpreted by the shell.
As a convenience, commas may also be used as separators, so that no
quoting is needed:
-Denable-sanitize-options=address,undefined. The available
sanitizers depend on the compiler and on its version: the dedicated
option of an unavailable sanitizer is simply ignored with a warning, so
that the same options can be used whatever the compiler is. The
address, thread and memory
sanitizers cannot be used simultaneously.
The combination which gives the best return for
TFEL/MFront is the address sanitizer combined with the
undefined behaviour sanitizer and its subsets:
With gcc, we recommend listing the checks of the
undefined behaviour sanitizer individually rather than using
undefined, as the vptr check, which is part of
undefined, may lead to pathologically long compilation
times for the heavy template code of MFront (see the
release notes):
$ cmake <srcdir> -B build -DCMAKE_BUILD_TYPE=Debug \
-Denable-sanitize-options="address;alignment;bool;bounds;bounds-strict;builtin;enum;float-cast-overflow;float-divide-by-zero;null;object-size;return;shift;shift-base;shift-exponent;signed-integer-overflow" \
-Denable-glibcxx-debug=ONWith clang, the undefined sanitizer can
be used directly:
$ CC=clang CXX=clang++ cmake <srcdir> -B build -DCMAKE_BUILD_TYPE=Debug \
-Denable-sanitize-options="address;undefined" \
-Denable-glibcxx-debug=ONNote that clang requires the runtimes of the sanitizers
(part of compiler-rt, often packaged as
libclang-rt-<version>-dev or
libclang-common-<version>-dev) to be installed: if
the sanitizer flags are rejected at link time, the corresponding
sanitizer is disabled by cmake with a
sanitizer '<name>' disabled message, and no sanitizer
flag is used.
The enable-glibcxx-debug option adds the
-D_GLIBCXX_DEBUG definition in debug builds, which enables
the debug mode of the standard library of the GNU C++ library (bounds
checking of the containers, valid iterator checks, etc.). It can be
combined with the sanitizers above.
With clang using the libc++ standard
library (enable-libcxx=ON), the
enable-libcxx-hardening-mode option enables the hardening
mode of libc++ instead.
The usual steps of the continuous integration, with sanitizers, are:
$ cmake --build build --config Debug
$ cmake --build build --config Debug --target build-tests
$ ctest --test-dir build --build-config DebugThe behaviour of the sanitizers at execution time is controlled by environment variables. We recommend the following settings to get full reports:
$ ASAN_OPTIONS=detect_leaks=1 UBSAN_OPTIONS=print_stacktrace=1 \
ctest --test-dir build --build-config DebugASAN_OPTIONS=detect_leaks=1 enables the leak sanitizer
with the address sanitizer (it is not enabled by default with
clang).UBSAN_OPTIONS=print_stacktrace=1 makes the undefined
behaviour sanitizer print a stack trace, which is much more useful than
a source location alone.A sanitizer report makes the tested program exit with a non zero
status, and thus the corresponding test fails: any sanitizer report is
reported by ctest as a test failure.
With -Denable-glibcxx-debug=ON, the executables of the
build tree must use the libraries of the build tree: the
_GLIBCXX_DEBUG mode changes the symbols of the functions
using standard containers (std::__debug::vector, etc.) and
mixing hardened and non hardened code gives
undefined symbol errors at startup.
This is a frequent issue for TFEL developers, because
LD_LIBRARY_PATH (TFELHOME, etc.) of the
development environment points to an installed, not hardened,
TFEL, and LD_LIBRARY_PATH has precedence over
the RUNPATH of the executables. In such a situation, the
tests fail immediately (in a fraction of a second) with messages such
as:
symbol lookup error: ...: undefined symbol: ...NSt7__debug6vector...To avoid this, run the tests in an environment free of the installed
TFEL:
$ unset TFELHOME TFELPLOTHOME TFELEDITORHOME
$ export LD_LIBRARY_PATH=$(echo "$LD_LIBRARY_PATH" | tr ':' '\n' | grep -v tfel | paste -sd:)
$ export PATH=$(echo "$PATH" | tr ':' '\n' | grep -v tfel | paste -sd:)
$ ctest --test-dir build --build-config Debug(the continuous integration machines have a clean environment, so this issue does not show up there).
TMPDIR)
have enough space. A full filesystem appears as compilation errors of
the form
error writing to /tmp/ccXXXXXX.s: No space left on device.TFEL (heavy
template instantiations with unit types) with sanitizers requires
several GB of memory per compilation process: on a 15 GB machine,
building the tests with more than four parallel jobs may exhaust the
memory, which appears as
fatal error: ... signal terminated program cc1plus
errors.Run sanitizers workflow runs this sequence
automatically on GitHub Actions: see the release howto.gcc and clang documentations describe
many more sanitizers: they can be declared in
cmake/modules/gcc.cmake and
cmake/modules/clang.cmake in the same way as the already
declared ones.libFuzzer based analyses of the tokenizer of
MFront files are described on a dedicated page.