Add sanitizer functionality (ASAN, LSAN, UBSAN) support

This change adds sanitizer toolchain functionality, which can help
identify issues within the lutok codebase.

Introduce GH action to run the tests with UBSAN enabled. Initial
scaffolding for ASAN/LSAN support is added, but not enabled via
GHA. Issues blocking its enablement are discussed more at length in
freebsd/atf#77.

Related to:	freebsd/atf#177
Signed-off-by: Enji Cooper <ngie@FreeBSD.org>

Author: ngie-eign

.github/workflows/build.yaml

@@ -10,10 +10,10 @@
 #     * Run tests
 #
 # On MacOS we build with:
-#   * latest clang from brew (system provided clang lacks sanitizers).
-#   * ld from system
+# * latest clang from brew (system provided clang lacks sanitizers).
+# * ld from system
 name: build
-on:  # yamllint disable-line rule:truthy
+"on":
     pull_request:
         branches:
             - master
@@ -24,20 +24,22 @@ permissions:
     contents: read
 
 jobs:
-    build:
-        name: build ${{ matrix.build-os }} ${{ matrix.compiler }}
+    build-and-test:
+        # yamllint disable-line rule:line-length
+        name: ${{ matrix.build-os }} ${{ matrix.compiler }} ${{ join(matrix.sanitize, '+') }}
         env:
             AR: ${{ matrix.llvm-bindir }}/llvm-ar
             CC: ${{ matrix.llvm-bindir }}/clang
             CPP: ${{ matrix.llvm-bindir }}/clang-cpp
             CXX: ${{ matrix.llvm-bindir }}/clang++
             NM: ${{ matrix.llvm-bindir }}/llvm-nm
-            RANLIB: ${{ matrix.llvm-bindir }}/llvm-ranlib
             OBJDUMP: ${{ matrix.llvm-bindir }}/llvm-objdump
+            RANLIB: ${{ matrix.llvm-bindir }}/llvm-ranlib
             STRIP: ${{ matrix.llvm-bindir }}/llvm-strip
             LUTOK_SRCDIR: ${{ github.workspace }}/src
             LUTOK_OBJDIR: ${{ github.workspace }}/obj
-            JOB_NAME: ${{ matrix.build-os }} ${{ matrix.compiler }}
+            # yamllint disable-line rule:line-length
+            JOB_NAME: ${{ matrix.build-os }} ${{ matrix.compiler }} ${{ join(matrix.sanitize, '+') }}
         runs-on: "${{ matrix.build-os }}"
         strategy:
             fail-fast: false
@@ -67,16 +69,23 @@ jobs:
                           - atf-sh
                           - autoconf
                           - automake
+                          - clang-18
                           - doxygen
                           - graphviz
                           - kyua
                           - libatf-dev
                           - liblua5.4-dev
                           - libtool
-                          - llvm-18
                           - lua5.4
                           - pkgconf
                       llvm-bindir: /usr/lib/llvm-18/bin
+                sanitize:
+                    - ""
+                    # TODO(ngie,77): tests currently fail when these options
+                    #                are enabled.
+                    # - ["asan", "lsan"]
+                    - ubsan
+
         steps:
             - name: Install packages (macOS)
               if: runner.os == 'macOS'
@@ -97,14 +106,26 @@ jobs:
             - name: Sanity checks
               run: |
                   which -a kyua
-            - name: Build
+            - name: Configure
               run: |
+                  CFG_ARGS="--enable-atf"
+                  for i in ${{ join(matrix.sanitize, ' ') }}; do
+                      CFG_ARGS="${CFG_ARGS} --enable-${i}"
+                  done
+                  echo "uname -a: $(uname -a)"
+                  echo "uname -m: $(uname -m)"
+                  echo "uname -p: $(uname -p)"
+                  echo "Build environment:"
+                  kyua about | head -1
+
                   cd "${LUTOK_SRCDIR}"
-                  ./admin/ci-build/01_configure.sh
+                  ./admin/ci-build/01_configure.sh ${CFG_ARGS}
             - name: Distcheck (builds and tests)
               run: |
-                  CFG_ARGS="--disable-dependency-tracking --enable-developer"
-                  CFG_ARGS="${CFG_ARGS} --enable-atf"
+                  CFG_ARGS="--disable-dependency-tracking --enable-atf"
+                  for i in ${{ join(matrix.sanitize, ' ') }}; do
+                      CFG_ARGS="${CFG_ARGS} --enable-${i}"
+                  done
                   cd "${LUTOK_SRCDIR}"
                   env "EXTRA_DISTCHECK_CONFIGURE_ARGS=${CFG_ARGS}" \
                       ./admin/ci-build/02_distcheck.sh

INSTALL.md

@@ -46,7 +46,6 @@ need the following tools:
 * GNU Automake 1.9 (or later).
 * GNU Libtool.
 
-
 # Regenerating the build system
 
 This is not necessary if you are building from a formal release
@@ -102,66 +101,94 @@ To build and install the source package, you must follow these steps:
 The most common, standard flags given to `configure` are:
 
 - `--prefix=directory`
-    - **Possible values**: any path
-    - **Default**: "/usr/local"
 
-      Specifies where the library (binaries and all associated files) will
-      be installed.
+  **Possible values**: any path
+  **Default**: "/usr/local"
 
-- `--help`
-      Shows information about all available flags and exits immediately,
-      without running any configuration tasks.
+  Specifies where the library (binaries and all associated files) will be
+  installed.
 
 The following flags are specific to Lutok's `configure` script:
 
-- `--enable-developer`
-    - **Possible values**: "yes", "no"
-    - **Default**: "yes" in Git HEAD builds; "no" in formal releases.
+- `--enable-developer`:
+
+  **Default:** `yes` in HEAD builds; `no` in release builds.
+
+  Enables several features useful for development, such as the inclusion
+  of debugging symbols in all objects or the enforcement of compilation
+  warnings.
+
+  The compiler will be executed with an exhaustive collection of warning
+  detection features regardless of the value of this flag. However, such
+  warnings are only fatal when `--enable-developer` is `yes`.
 
-      Enables several features useful for development, such as the inclusion
-      of debugging symbols in all objects or the enforcement of compilation
-      warnings.
+- `--enable-asan`
 
-      The compiler will be executed with an exhaustive collection of warning
-      detection features regardless of the value of this flag.  However, such
-      warnings are only fatal when `--enable-developer` is set to "yes".
+  **Default:** `no`.
+
+  Enables ASAN (Address Sanitizer) compiler support in the toolchain.
+
+  Platform-specific support varies depending on the toolchain and OS.
 
 - `--enable-atf`
-    - **Possible values**: "yes", "no", "auto".
-    - **Default**: "auto"
 
-      Enables usage of ATF to build (and later install) the tests.
+  **Possible values**: "yes", "no", "auto".
+  **Default**: "auto"
+
+  Enables usage of ATF to build (and later install) the tests.
+
+  Setting this to "yes" causes the `configure` script to look for ATF
+  unconditionally and abort if not found.  Setting this to "auto" lets
+  `configure` perform the best decision based on availability of ATF.
+  Setting this to "no" explicitly disables ATF usage.
+
+  When support for tests is enabled, the build process will generate the
+  test programs and will later install them into the tests tree.
+  Running `make check` or `make installcheck` from within the source
+  directory will cause these tests to be run with Kyua (assuming it is
+  also installed).
+
+- `--enable-lsan`
+
+  **Default:** `no`.
+
+  Enables LSAN (Leak Sanitizer) compiler support in the toolchain.
+
+  Platform-specific support varies depending on the toolchain and OS.
+
+  **Important:**
+  * llvm support is only available in Linux and macOS at time of writing.
+  * The test suite does not currently pass with this option enabled. See
+    [Issue #77](https://github.com/freebsd/atf/issues/77) for more details.
+
+- `--enable-ubsan`
+
+  **Default:** `no`.
 
-      Setting this to "yes" causes the `configure` script to look for ATF
-      unconditionally and abort if not found.  Setting this to "auto" lets
-      `configure` perform the best decision based on availability of ATF.
-      Setting this to "no" explicitly disables ATF usage.
+  Enables UBSAN (Undefined Behavior Sanitizier) compiler support in the
+  toolchain.
 
-      When support for tests is enabled, the build process will generate the
-      test programs and will later install them into the tests tree.
-      Running `make check` or `make installcheck` from within the source
-      directory will cause these tests to be run with Kyua (assuming it is
-      also installed).
+  Platform-specific support varies depending on the toolchain and OS.
 
 - `--with-doxygen`
-    - **Possible values**: "yes", "no", "auto", or a path.
-    - **Default**: "auto".
 
-      Enables usage of Doxygen to generate documentation for internal APIs.
+  **Possible values**: "yes", "no", "auto", or a path.
+  **Default**: "auto".
 
-      Setting this to "yes" causes the `configure` script to look for Doxygen
-      unconditionally and abort if not found.  Setting this to "auto" lets
-      `configure` perform the best decision based on availability of Doxygen.
-      Setting this to "no" explicitly disables Doxygen usage.  And, lastly,
-      setting this to a path forces `configure` to use a specific Doxygen
-      binary, which must exist.
+  Enables usage of Doxygen to generate documentation for internal APIs.
 
-      When support for Doxygen is enabled, the build process will generate
-      HTML documentation for the Lutok API.  This documentation will later
-      be installed in the HTML directory specified by the `configure` script.
-      You can change the location of the HTML documents by providing your
-      desired override with the `--htmldir` flag to the `configure` script.
+  Setting this to "yes" causes the `configure` script to look for Doxygen
+  unconditionally and abort if not found.  Setting this to "auto" lets
+  `configure` perform the best decision based on availability of Doxygen.
+  Setting this to "no" explicitly disables Doxygen usage.  And, lastly,
+  setting this to a path forces `configure` to use a specific Doxygen
+  binary, which must exist.
 
+  When support for Doxygen is enabled, the build process will generate
+  HTML documentation for the Lutok API.  This documentation will later
+  be installed in the HTML directory specified by the `configure` script.
+  You can change the location of the HTML documents by providing your
+  desired override with the `--htmldir` flag to the `configure` script.
 
 Run the tests!
 ==============

Makefile.am

@@ -26,6 +26,28 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+#
+# Supporting logic to run our custom testsuite.
+#
+
+TESTS_ENVIRONMENT = PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig
+
+if HAVE_ASAN
+# NB: the trailing comma is intentional. I hate automake not allowing `:=` use on subsequent lines.
+if HAVE_LSAN
+LSAN_OPTIONS = detect_leaks=1,
+else
+LSAN_OPTIONS =
+endif
+# Some of the testcases trigger false positives as they pass
+# `SIZE_MAX - 1`, etc, to malloc(3).
+ASAN_OPTIONS = ${LSAN_OPTIONS}allocator_may_return_null=1
+TESTS_ENVIRONMENT+= ASAN_OPTIONS=${ASAN_OPTIONS}
+endif
+if HAVE_UBSAN
+TESTS_ENVIRONMENT+= UBSAN_OPTIONS=print_stacktrace=1:halt_on_error=1
+endif
+
 ACLOCAL_AMFLAGS = -I m4
 
 doc_DATA = AUTHORS COPYING NEWS README.md
@@ -80,6 +102,8 @@ lutok.pc: $(srcdir)/lutok.pc.in Makefile
 	    -e 's#__LIBDIR__#$(libdir)#g' \
 	    -e 's#__LUA_CFLAGS__#$(LUA_CFLAGS)#g' \
 	    -e 's#__LUA_LIBS__#$(LUA_LIBS)#g' \
+	    -e 's#__PC_CXXFLAGS__#$(pc_cxxflags)#g' \
+	    -e 's#__PC_LDFLAGS__#$(pc_ldflags)#g' \
 	    -e 's#__VERSION__#$(PACKAGE_VERSION)#g' \
 	    <$(srcdir)/lutok.pc.in >lutok.pc.tmp; \
 	mv lutok.pc.tmp lutok.pc
@@ -143,19 +167,38 @@ state_test_SOURCES = state_test.cpp test_utils.hpp
 state_test_CXXFLAGS = $(LUTOK_CFLAGS) $(ATF_CXX_CFLAGS)
 state_test_LDADD = $(LUTOK_LIBS) $(ATF_CXX_LIBS)
 
-if HAVE_KYUA
-TESTS_ENVIRONMENT = PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig
-
 check-local: check-kyua
 PHONY_TARGETS += check-kyua
 check-kyua:
 	$(TESTS_ENVIRONMENT) kyua test \
 	    --kyuafile='$(top_srcdir)/Kyuafile' --build-root='$(top_builddir)'
 
+INSTALLCHECK_TARGETS =
+
+testsdir = $(exec_prefix)/tests
+pkgtestsdir = $(testsdir)/$(PACKAGE)
+
 installcheck-local: installcheck-kyua
 PHONY_TARGETS += installcheck-kyua
+if HAVE_KYUA
+
+INSTALLCHECK_TARGETS += installcheck-kyua
+
 installcheck-kyua:
-	cd $(testsdir) && $(TESTS_ENVIRONMENT) kyua test
+	set +e; cd $(pkgtestsdir) && $(TESTS_ENVIRONMENT) \
+	    $(KYUA) --config='$(KYUA_TEST_CONFIG_FILE)' test; \
+	ret=$$?; \
+	echo $$ret; \
+	if [ -n "$$JUNIT_OUTPUT" ]; then \
+	    cd $(pkgtestsdir) && $(TESTS_ENVIRONMENT) \
+		    $(KYUA) --config='$(KYUA_TEST_CONFIG_FILE)' \
+		    report-junit --output="$$JUNIT_OUTPUT"; \
+	    sed -i '.orig' 's/encoding="iso-8859-1"/encoding="utf-8"/' "$$JUNIT_OUTPUT"; \
+	    rm -f "$$JUNIT_OUTPUT.orig"; \
+	fi; \
+	cd $(pkgtestsdir) && $(TESTS_ENVIRONMENT) \
+		$(KYUA) --config='$(KYUA_TEST_CONFIG_FILE)' report --verbose; \
+	exit $$ret
 endif
 else
 DIST_HOOKS += dist-no-atf
@@ -220,4 +263,6 @@ clean-all:
 
 dist-hook: $(DIST_HOOKS)
 
-.PHONY: ${PHONY_TARGETS}
+.PHONY: $(PHONY_TARGETS)
+
+# vim: syntax=make:noexpandtab:shiftwidth=8:softtabstop=8

admin/ci-build/01_configure.sh

@@ -17,7 +17,7 @@ fi
 # shellcheck disable=SC2086
 autoreconf ${autoreconf_args}
 
-if ! ./configure --enable-atf; then
+if ! ./configure $*; then
     cat config.log || true
     exit 1
 fi

admin/ci-build/02_distcheck.sh

@@ -19,9 +19,8 @@ set -eux
 NPROC=$(nproc 2>/dev/null || getconf NPROCESSORS_ONLN 2>/dev/null || echo 1)
 
 f="--enable-atf"
-f="${f} ATF_BUILD_CC='${CC}'"
-f="${f} ATF_BUILD_CXX='${CXX}'"
-# Is this being run in a git clone, or with a release artifact?
+# Is this being run in a git clone, or with a release artifact? If the former,
+# automatically enable developer mode.
 if git rev-parse --is-inside-work-tree; then
     f="${f} --enable-developer"
 fi
@@ -47,4 +46,4 @@ ${sudo} env PATH="${PATH}" make distcheck -j"${NPROC}" \
     DISTCHECK_CONFIGURE_FLAGS="${f}" \
     KYUA_TEST_CONFIG_FILE="${kyua_conf}"
 
-# vim: syntax=sh:expandtab:shiftwidth=4:softtabstop=4
+# vim: syntax=sh:expandtab:shiftwidth=4:softtabstop=4:textwidth=80