Test the simdutf backend in CI

JSON_USE_SIMDUTF was documented and shipped but never compiled by anything in
the repository, so nothing held the backend to the behavior the docs promise.

Add JSON_TestSimdutf (OFF by default), which fetches simdutf and defines
JSON_USE_SIMDUTF for every test target, and a ci_test_simdutf target that runs
the whole suite in that configuration. Because simdutf needs C++17, the suite is
built at C++11 as well, so one job covers both the scalar fallback with the
macro defined and simdutf itself.

The dependency hangs off test_main, whose usage requirements every test target
inherits. The library target and the installed CMake package are deliberately
untouched: making nlohmann_json link simdutf would put a find_dependency() in
the exported package, which is a separate decision.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MXDi7NTMKAmoArUZSKMc4T
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

.github/workflows/ubuntu.yml

@@ -100,7 +100,7 @@ jobs:
     container: ubuntu:focal
     strategy:
       matrix:
-        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls]
+        target: [ci_cmake_flags, ci_test_diagnostics, ci_test_diagnostic_positions, ci_test_noexceptions, ci_test_noimplicitconversions, ci_test_legacycomparison, ci_test_noglobaludls, ci_test_simdutf]
     steps:
       - name: Install build-essential
         run: apt-get update ; apt-get install -y build-essential unzip wget git libssl-dev

cmake/ci.cmake

@@ -212,6 +212,24 @@ add_custom_target(ci_test_legacycomparison
     COMMENT "Compile and test with legacy discarded value comparison enabled"
 )
 
+###############################################################################
+# Validate UTF-8 with simdutf.
+###############################################################################
+
+add_custom_target(ci_test_simdutf
+    COMMAND ${CMAKE_COMMAND}
+    -DCMAKE_BUILD_TYPE=Debug -GNinja
+    -DJSON_BuildTests=ON -DJSON_TestSimdutf=ON
+    # simdutf needs C++17, so the library falls back to its scalar validator
+    # below that: build the suite at C++11 to cover the fallback with the macro
+    # defined, and at C++17 to run every test against simdutf itself
+    "-DJSON_TestStandards=11\;17"
+    -S${PROJECT_SOURCE_DIR} -B${PROJECT_BINARY_DIR}/build_simdutf
+    COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/build_simdutf
+    COMMAND cd ${PROJECT_BINARY_DIR}/build_simdutf && ${CMAKE_CTEST_COMMAND} --parallel ${N} --output-on-failure
+    COMMENT "Compile and test with simdutf UTF-8 validation enabled"
+)
+
 ###############################################################################
 # Enable brace-init copy semantics.
 ###############################################################################

docs/mkdocs/docs/api/macros/json_use_simdutf.md

@@ -60,6 +60,12 @@ By default, `#!cpp JSON_USE_SIMDUTF` is not defined and the portable C++11 scala
     target_link_libraries(your_target PRIVATE simdutf::simdutf)
     ```
 
+!!! hint "Testing this configuration"
+
+    The unit tests can be built against the simdutf backend with the CMake option `JSON_TestSimdutf` (`OFF` by
+    default), which fetches simdutf and defines `JSON_USE_SIMDUTF` for every test target. The `ci_test_simdutf` target
+    runs the whole test suite in that configuration.
+
 ## Version history
 
 - Added in version 3.13.0.

tests/CMakeLists.txt

@@ -2,6 +2,9 @@ cmake_minimum_required(VERSION 3.13...4.0)
 
 option(JSON_Valgrind    "Execute test suite with Valgrind." OFF)
 option(JSON_FastTests   "Skip expensive/slow tests." OFF)
+option(JSON_TestSimdutf "Build the unit tests against the simdutf UTF-8 validation backend." OFF)
+
+set(JSON_SIMDUTF_VERSION 9.1.0 CACHE STRING "The simdutf version used by JSON_TestSimdutf.")
 
 set(JSON_32bitTest     AUTO CACHE STRING "Enable the 32bit unit test (ON/OFF/AUTO/ONLY).")
 set(JSON_TestStandards "" CACHE STRING "The list of standards to test explicitly.")
@@ -88,6 +91,43 @@ target_include_directories(test_main PUBLIC
     ${PROJECT_BINARY_DIR}/include)
 target_link_libraries(test_main PUBLIC ${NLOHMANN_JSON_TARGET_NAME})
 
+#############################################################################
+# optionally validate UTF-8 with simdutf (JSON_USE_SIMDUTF)
+#############################################################################
+
+# The simdutf backend is opt-in and not vendored, so it is fetched here rather
+# than being a checked-in dependency. Everything below hangs off test_main,
+# whose usage requirements every test target inherits; the library target and
+# the installed CMake package are deliberately left untouched.
+if (JSON_TestSimdutf)
+    if (CMAKE_VERSION VERSION_LESS 3.18)
+        message(FATAL_ERROR "JSON_TestSimdutf requires CMake 3.18 or later (simdutf's minimum).")
+    endif()
+
+    include(FetchContent)
+
+    # simdutf builds its tests and tools by default, and its tests pull further
+    # dependencies of their own; only the library itself is needed here
+    set(SIMDUTF_TESTS OFF CACHE BOOL "" FORCE)
+    set(SIMDUTF_TOOLS OFF CACHE BOOL "" FORCE)
+    set(SIMDUTF_BENCHMARKS OFF CACHE BOOL "" FORCE)
+    set(SIMDUTF_ICONV OFF CACHE BOOL "" FORCE)
+
+    FetchContent_Declare(simdutf
+        URL https://github.com/simdutf/simdutf/archive/refs/tags/v${JSON_SIMDUTF_VERSION}.tar.gz
+        DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+    )
+    FetchContent_MakeAvailable(simdutf)
+
+    target_compile_definitions(test_main PUBLIC JSON_USE_SIMDUTF)
+    target_link_libraries(test_main PUBLIC simdutf::simdutf)
+
+    # simdutf.h requires C++17; below that the library keeps its scalar
+    # validator, so the C++11/14 test targets exercise the fallback and the
+    # C++17-and-later ones exercise simdutf. Both must agree.
+    message(STATUS "UTF-8 validation delegated to simdutf ${JSON_SIMDUTF_VERSION} for C++17 and later (JSON_USE_SIMDUTF)")
+endif()
+
 #############################################################################
 # define test- and standard-specific build settings
 #############################################################################