externals: add Catch2

problem: writing unit tests with manual fixtures and no value reporting
is slow, and prone to making debugging slow

solution: add the best C++ unit testing library as an external, try to
use it from the system to save build times

.typos.toml

@@ -4,6 +4,7 @@
 extend-exclude = [
   "cmake/sanitizers-cmake/*",
   "config/*",
+  "external/*",
   "m4/*",
   "src/common/libutil/json.hpp",
   "src/common/yggdrasil/*",

cmake/config_testing.cmake

@@ -2,6 +2,13 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
   include(CTest)
 endif()
 
+# Try to use installed catch2 to save build time, require at least version 3
+find_package(Catch2 3 CONFIG)
+if (NOT Catch2_FOUND)
+    add_subdirectory(external/catch2)
+endif ()
+include(Catch)
+
 set(TEST_ENV)
 set(FLUX_CO_INST "")
 if(FLUX_PREFIX EQUAL CMAKE_INSTALL_PREFIX)
@@ -18,6 +25,15 @@ list(APPEND TEST_ENV "FLUX_SCHED_EXEC_DIR=${FLUX_CMD_DIR}")
 list(APPEND TEST_ENV "FLUX_SCHED_PYTHON_SITELIB=${PYTHON_INSTALL_SITELIB}")
 
 # add maybe-installtest to the start
+function(flux_config_test)
+  set(options "")
+  set(oneValueArgs NAME COMMAND)
+  set(multiValueArgs "")
+
+  cmake_parse_arguments(PARSE_ARGV 0 ARG
+    "${options}" "${oneValueArgs}" "${multiValueArgs}")
+  set_property(TEST ${ARG_NAME} PROPERTY ENVIRONMENT "${TEST_ENV}")
+endfunction()
 function(flux_add_test)
   # This odd construction is as close as we can get to
   # generic argument forwarding
@@ -42,5 +58,6 @@ function(flux_add_test)
       COMMAND ${CMAKE_SOURCE_DIR}/t/scripts/maybe-installtest ${ARG_COMMAND}
       ${__argsQuoted}
     ) ")
-    set_property(TEST ${ARG_NAME} PROPERTY ENVIRONMENT "${TEST_ENV}")
+    flux_config_test(NAME ${ARG_NAME})
 endfunction()
+

external/CMakeLists.txt

@@ -0,0 +1,2 @@
+# catch2 is managed in cmake/config_testing.cmake to ensure its scope
+# covers all test builds

external/catch2/.bazelrc

@@ -0,0 +1,11 @@
+build --enable_platform_specific_config
+
+build:gcc9 --cxxopt=-std=c++2a
+build:gcc11 --cxxopt=-std=c++2a
+build:clang13 --cxxopt=-std=c++17
+build:vs2019 --cxxopt=/std:c++17
+build:vs2022 --cxxopt=/std:c++17
+
+build:windows --config=vs2022
+build:linux --config=gcc11
+build:macos --cxxopt=-std=c++2b

external/catch2/.clang-format

@@ -0,0 +1,45 @@
+---
+Language: Cpp
+Standard: c++14
+
+# Note that we cannot use IncludeIsMainRegex functionality, because it
+# does not support includes in angle brackets (<>)
+SortIncludes: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: <catch2/.*\.hpp>
+    Priority: 1
+  - Regex: <.*/.*\.hpp>
+    Priority: 2
+  - Regex: <.*>
+    Priority: 3
+
+AllowShortBlocksOnASingleLine: Always
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: WithoutElse
+AllowShortLambdasOnASingleLine: Inline
+
+AccessModifierOffset: "-4"
+AlignEscapedNewlines: Left
+AllowAllConstructorInitializersOnNextLine: "true"
+BinPackArguments: "false"
+BinPackParameters: "false"
+BreakConstructorInitializers: AfterColon
+ConstructorInitializerAllOnOneLineOrOnePerLine: "true"
+DerivePointerAlignment: "false"
+FixNamespaceComments: "true"
+IndentCaseLabels: "false"
+IndentPPDirectives: AfterHash
+IndentWidth: "4"
+NamespaceIndentation: All
+PointerAlignment: Left
+SpaceBeforeCtorInitializerColon: "false"
+SpaceInEmptyParentheses: "false"
+SpacesInParentheses: "true"
+TabWidth: "4"
+UseTab: Never
+AlwaysBreakTemplateDeclarations: Yes
+SpaceAfterTemplateKeyword: true
+SortUsingDeclarations: true
+ReflowComments: true

external/catch2/.clang-tidy

@@ -0,0 +1,81 @@
+---
+# Note: Alas, `Checks` is a string, not an array.
+#       Comments in the block string are not parsed and are passed in the value.
+#       They must thus be delimited by ',' from either side - then they are
+#       harmless. It's terrible, but it works.
+Checks: >-
+  clang-diagnostic-*,
+  clang-analyzer-*,
+  -clang-analyzer-optin.core.EnumCastOutOfRange,
+
+  bugprone-*,
+  -bugprone-unchecked-optional-access,
+  ,# This is ridiculous, as it triggers on constants,
+  -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-easily-swappable-parameters,
+  ,# Is not really useful, has false positives, triggers for no-noexcept move constructors ...,
+  -bugprone-exception-escape,
+  -bugprone-narrowing-conversions,
+  -bugprone-chained-comparison,# RIP decomposers,
+
+  modernize-*,
+  -modernize-avoid-c-arrays,
+  -modernize-use-auto,
+  -modernize-use-emplace,
+  -modernize-use-nullptr,# it went crazy with three-way comparison operators,
+  -modernize-use-trailing-return-type,
+  -modernize-return-braced-init-list,
+  -modernize-concat-nested-namespaces,
+  -modernize-use-nodiscard,
+  -modernize-use-default-member-init,
+  -modernize-type-traits,# we need to support C++14,
+  -modernize-deprecated-headers,
+  ,# There's a lot of these and most of them are probably not useful,
+  -modernize-pass-by-value,
+
+  performance-*,
+  -performance-enum-size,
+
+  portability-*,
+
+  readability-*,
+  -readability-braces-around-statements,
+  -readability-container-size-empty,
+  -readability-convert-member-functions-to-static,
+  -readability-else-after-return,
+  -readability-function-cognitive-complexity,
+  -readability-function-size,
+  -readability-identifier-length,
+  -readability-implicit-bool-conversion,
+  -readability-isolate-declaration,
+  -readability-magic-numbers,
+  -readability-named-parameter,
+  -readability-qualified-auto,
+  -readability-redundant-access-specifiers,
+  -readability-simplify-boolean-expr,
+  -readability-static-definition-in-anonymous-namespace,
+  -readability-uppercase-literal-suffix,
+  -readability-use-anyofallof,
+  -readability-avoid-return-with-void-value,
+
+  ,# time hogs,
+  -bugprone-throw-keyword-missing,
+  -modernize-replace-auto-ptr,
+  -readability-identifier-naming,
+
+  ,# We cannot use this until clang-tidy supports custom unique_ptr,
+  -bugprone-use-after-move,
+  ,# Doesn't recognize unevaluated context in CATCH_MOVE and CATCH_FORWARD,
+  -bugprone-macro-repeated-side-effects,
+WarningsAsErrors: >-
+  clang-analyzer-core.*,
+  clang-analyzer-cplusplus.*,
+  clang-analyzer-security.*,
+  clang-analyzer-unix.*,
+  performance-move-const-arg,
+  performance-unnecessary-value-param,
+  readability-duplicate-include,
+HeaderFilterRegex: '.*\.(c|cxx|cpp)$'
+FormatStyle:     none
+CheckOptions: {}
+...

external/catch2/.conan/build.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import os
+import re
+from cpt.packager import ConanMultiPackager
+from cpt.ci_manager import CIManager
+from cpt.printer import Printer
+
+
+class BuilderSettings(object):
+    @property
+    def username(self):
+        """ Set catchorg as package's owner
+        """
+        return os.getenv("CONAN_USERNAME", "catchorg")
+
+    @property
+    def login_username(self):
+        """ Set Bintray login username
+        """
+        return os.getenv("CONAN_LOGIN_USERNAME", "horenmar")
+
+    @property
+    def upload(self):
+        """ Set Catch2 repository to be used on upload.
+            The upload server address could be customized by env var
+            CONAN_UPLOAD. If not defined, the method will check the branch name.
+            Only devel or CONAN_STABLE_BRANCH_PATTERN will be accepted.
+            The devel branch will be pushed to testing channel, because it does
+            not match the stable pattern. Otherwise it will upload to stable
+            channel.
+        """
+        return os.getenv("CONAN_UPLOAD", "https://api.bintray.com/conan/catchorg/catch2")
+
+    @property
+    def upload_only_when_stable(self):
+        """ Force to upload when running over tag branch
+        """
+        return os.getenv("CONAN_UPLOAD_ONLY_WHEN_STABLE", "True").lower() in ["true", "1", "yes"]
+
+    @property
+    def stable_branch_pattern(self):
+        """ Only upload the package the branch name is like a tag
+        """
+        return os.getenv("CONAN_STABLE_BRANCH_PATTERN", r"v\d+\.\d+\.\d+")
+
+    @property
+    def reference(self):
+        """ Read project version from branch create Conan reference
+        """
+        return os.getenv("CONAN_REFERENCE", "catch2/{}".format(self._version))
+
+    @property
+    def channel(self):
+        """ Default Conan package channel when not stable
+        """
+        return os.getenv("CONAN_CHANNEL", "testing")
+
+    @property
+    def _version(self):
+        """ Get version name from cmake file
+        """
+        pattern = re.compile(r"project\(Catch2 LANGUAGES CXX VERSION (\d+\.\d+\.\d+)\)")
+        version = "latest"
+        with open("CMakeLists.txt") as file:
+            for line in file:
+                result = pattern.search(line)
+                if result:
+                    version = result.group(1)
+        return version
+
+    @property
+    def _branch(self):
+        """ Get branch name from CI manager
+        """
+        printer = Printer(None)
+        ci_manager = CIManager(printer)
+        return ci_manager.get_branch()
+
+
+if __name__ == "__main__":
+    settings = BuilderSettings()
+    builder = ConanMultiPackager(
+        reference=settings.reference,
+        channel=settings.channel,
+        upload=settings.upload,
+        upload_only_when_stable=False,
+        stable_branch_pattern=settings.stable_branch_pattern,
+        login_username=settings.login_username,
+        username=settings.username,
+        test_folder=os.path.join(".conan", "test_package"))
+    builder.add()
+    builder.run()

external/catch2/.conan/test_package/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.15)
+project(PackageTest CXX)
+
+find_package(Catch2 CONFIG REQUIRED)
+
+add_executable(test_package test_package.cpp)
+target_link_libraries(test_package Catch2::Catch2WithMain)
+target_compile_features(test_package PRIVATE cxx_std_14)

external/catch2/.conan/test_package/conanfile.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from conan import ConanFile
+from conan.tools.cmake import CMake, cmake_layout
+from conan.tools.build import can_run
+from conan.tools.files import save, load
+import os
+
+
+class TestPackageConan(ConanFile):
+    settings = "os", "compiler", "build_type", "arch"
+    generators = "CMakeToolchain", "CMakeDeps", "VirtualRunEnv"
+    test_type = "explicit"
+
+    def requirements(self):
+        self.requires(self.tested_reference_str)
+
+    def layout(self):
+        cmake_layout(self)
+
+    def generate(self):
+        save(self, os.path.join(self.build_folder, "package_folder"),
+             self.dependencies[self.tested_reference_str].package_folder)
+        save(self, os.path.join(self.build_folder, "license"),
+             self.dependencies[self.tested_reference_str].license)
+
+    def build(self):
+        cmake = CMake(self)
+        cmake.configure()
+        cmake.build()
+
+    def test(self):
+        if can_run(self):
+            cmd = os.path.join(self.cpp.build.bindir, "test_package")
+            self.run(cmd, env="conanrun")
+
+            package_folder = load(self, os.path.join(self.build_folder, "package_folder"))
+            license = load(self, os.path.join(self.build_folder, "license"))
+            assert os.path.isfile(os.path.join(package_folder, "licenses", "LICENSE.txt"))
+            assert license == 'BSL-1.0'

external/catch2/.conan/test_package/test_package.cpp

@@ -0,0 +1,13 @@
+#include <catch2/catch_test_macros.hpp>
+
+int Factorial( int number ) {
+    return number <= 1 ? 1 : Factorial( number - 1 ) * number;
+}
+
+TEST_CASE( "Factorial Tests", "[single-file]" ) {
+    REQUIRE( Factorial(0) == 1 );
+    REQUIRE( Factorial(1) == 1 );
+    REQUIRE( Factorial(2) == 2 );
+    REQUIRE( Factorial(3) == 6 );
+    REQUIRE( Factorial(10) == 3628800 );
+}

external/catch2/.gitattributes

@@ -0,0 +1,22 @@
+# This sets the default behaviour, overriding core.autocrlf
+* text=auto
+
+# All source files should have unix line-endings in the repository,
+# but convert to native line-endings on checkout
+*.cpp text
+*.h text
+*.hpp text
+
+# Windows specific files should retain windows line-endings
+*.sln text eol=crlf
+
+# Keep executable scripts with LFs so they can be run after being
+# checked out on Windows
+*.py text eol=lf
+
+
+# Keep the single include header with LFs to make sure it is uploaded,
+# hashed etc with LF
+single_include/**/*.hpp eol=lf
+# Also keep the LICENCE file with LFs for the same reason
+LICENCE.txt eol=lf

external/catch2/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: "horenmar"
+custom: "https://www.paypal.me/horenmar"