Merge remote-tracking branch 'origin/dev' into coverage-llm

# Conflicts:
#	.codecov.yml

.codecov.yml

@@ -19,6 +19,15 @@ coverage:
       default:
         target: auto
         threshold: 2%
+        paths:
+          # PeerImp is historically hard to exercise in the current unit-test
+          # harness. Keep this list narrow; new testable code should remain
+          # covered by the default patch gate.
+          - "!src/xrpld/overlay/detail/PeerImp.cpp"
+      historically-untested:
+        target: 0%
+        paths:
+          - "src/xrpld/overlay/detail/PeerImp.cpp"
     changes: false
 
 github_checks:

.github/actions/xahau-ga-dependencies/action.yml

@@ -50,6 +50,10 @@ inputs:
     options:
       - libstdcxx
       - libcxx
+  conan_deps_cxxflags:
+    description: 'Extra cxxflags applied to Conan dependency package builds only (NOT the rippled build). JSON object keyed by Conan package pattern, e.g. {"grpc/*":["-Wno-foo"]}. Maps to <pattern>:tools.build:cxxflags.'
+    required: false
+    default: '{}'
 
 outputs:
   cache-hit:
@@ -81,6 +85,8 @@ runs:
 
     - name: Configure Conan
       shell: bash
+      env:
+        CONAN_DEPS_CXXFLAGS: ${{ inputs.conan_deps_cxxflags }}
       run: |
         # Create the default profile directory if it doesn't exist
         mkdir -p ~/.conan2/profiles
@@ -105,7 +111,14 @@ runs:
         os=${{ inputs.os }}
         EOF
 
-        # Add buildenv and conf sections for Linux (not needed for macOS)
+        # [buildenv] + [conf] sections.
+        # Linux pins compiler executables; macOS uses the system toolchain.
+        # conan_deps_cxxflags (matrix-driven) optionally adds package-pattern
+        # scoped tools.build:cxxflags for Conan dependency builds only - typically
+        # grpc workarounds for newer clang's stricter diagnostics. Because these
+        # are profile-pattern scoped (e.g. grpc/*:...), they do NOT affect the
+        # consumer/rippled toolchain generated for the main build.
+        NEED_CONF=0
         if [ "${{ inputs.os }}" = "Linux" ] && [ -n "${{ inputs.cc }}" ]; then
           cat >> ~/.conan2/profiles/default <<EOF
 
@@ -116,16 +129,38 @@ runs:
         [conf]
         tools.build:compiler_executables={"c": "/usr/bin/${{ inputs.cc }}", "cpp": "/usr/bin/${{ inputs.cxx }}"}
         EOF
+          NEED_CONF=1
         fi
 
-        # Add macOS-specific conf if needed
-        if [ "${{ inputs.os }}" = "Macos" ]; then
-          cat >> ~/.conan2/profiles/default <<EOF
+        if [ -n "${CONAN_DEPS_CXXFLAGS}" ] && [ "${CONAN_DEPS_CXXFLAGS}" != "{}" ]; then
+          CONAN_DEPS_CXXFLAGS_LINES="$(python3 - <<'PY'
+        import json
+        import os
+        import sys
 
-        [conf]
-        # Workaround for gRPC with newer Apple Clang
-        tools.build:cxxflags=["-Wno-missing-template-arg-list-after-template-kw"]
-        EOF
+        raw = os.environ["CONAN_DEPS_CXXFLAGS"]
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            sys.exit("conan_deps_cxxflags must be a JSON object like {\"grpc/*\": [\"-Wno-...\"]}")
+
+        for pattern, flags in data.items():
+            if not isinstance(pattern, str) or not pattern:
+                sys.exit("conan_deps_cxxflags keys must be non-empty Conan package patterns")
+            if pattern == "&":
+                sys.exit("conan_deps_cxxflags must target dependency package patterns, not the consumer (&)")
+            if not isinstance(flags, list) or not all(isinstance(flag, str) for flag in flags):
+                sys.exit(f"{pattern}: cxxflags must be a JSON string list")
+            if flags:
+                print(f"{pattern}:tools.build:cxxflags={json.dumps(flags, separators=(',', ':'))}")
+        PY
+          )"
+          if [ -n "${CONAN_DEPS_CXXFLAGS_LINES}" ] && [ "$NEED_CONF" = "0" ]; then
+            echo "" >> ~/.conan2/profiles/default
+            echo "[conf]" >> ~/.conan2/profiles/default
+          fi
+          if [ -n "${CONAN_DEPS_CXXFLAGS_LINES}" ]; then
+            printf '%s\n' "${CONAN_DEPS_CXXFLAGS_LINES}" >> ~/.conan2/profiles/default
+          fi
         fi
 
         # Display profile for verification

.github/workflows/xahau-ga-macos.yml

@@ -107,6 +107,9 @@ jobs:
           compiler: apple-clang
           compiler_version: ${{ steps.detect-compiler.outputs.compiler_version }}
           stdlib: libcxx
+          # grpc 1.50.1 trips clang-19+ -Werror=missing-template-arg-list-after-template-kw
+          # on Apple Clang. Drop when grpc is bumped past the fix.
+          conan_deps_cxxflags: '{"grpc/*":["-Wno-missing-template-arg-list-after-template-kw"]}'
 
       - name: Build
         uses: ./.github/actions/xahau-ga-build

.github/workflows/xahau-ga-nix.yml

@@ -72,15 +72,26 @@ jobs:
                   "job_type": "build"
               },
               {
-                  "compiler_id": "gcc-13-libstdcxx",
-                  "compiler": "gcc",
-                  "cc": "gcc-13",
-                  "cxx": "g++-13",
-                  "gcov": "gcov-13",
-                  "compiler_version": 13,
-                  "stdlib": "default",
+                  # Latest stable Clang for the most accurate source-based
+                  # coverage mapping (newer language features, fewer bugs in
+                  # llvm-cov region inference). Pulled from apt.llvm.org since
+                  # Ubuntu 24.04 default repos cap at clang-18.
+                  "compiler_id": "clang-20-libcxx",
+                  "compiler": "clang",
+                  "cc": "clang-20",
+                  "cxx": "clang++-20",
+                  "compiler_version": 20,
+                  "stdlib": "libcxx",
                   "configuration": "Debug",
-                  "job_type": "coverage"
+                  "job_type": "coverage",
+                  "coverage_tool": "llvm",
+                  "coverage_format": "lcov",
+                  # grpc 1.50.1 uses `Foo::template Bar(...)` without an
+                  # angle-bracket arg list; clang-19+ promoted that to
+                  # -Werror. Drop when grpc is bumped past the fix.
+                  "conan_deps_cxxflags": {
+                      "grpc/*": ["-Wno-missing-template-arg-list-after-template-kw"]
+                  }
               },
               {
                   "compiler_id": "clang-14-libstdcxx-gcc11",
@@ -131,7 +142,7 @@ jobs:
           # Minimal matrix for PRs and feature branches
           minimal_matrix = [
               full_matrix[1],  # gcc-13 (middle-ground gcc)
-              full_matrix[2],  # gcc-13 coverage
+              full_matrix[2],  # clang-20 llvm-cov coverage
               full_matrix[3]   # clang-14 (mature, stable clang)
           ]
           
@@ -207,9 +218,9 @@ jobs:
           # Select the appropriate matrix
           if use_full:
               if force_full:
-                  print(f"Using FULL matrix (7 configs) - forced by [ci-nix-full-matrix] tag")
+                  print(f"Using FULL matrix (7 configs (build x6 + clang-20 llvm-cov coverage)) - forced by [ci-nix-full-matrix] tag")
               else:
-                  print(f"Using FULL matrix (7 configs) - targeting main branch")
+                  print(f"Using FULL matrix (7 configs (build x6 + clang-20 llvm-cov coverage)) - targeting main branch")
               matrix = full_matrix
           else:
               print(f"Using MINIMAL matrix (3 configs) - feature branch/PR")
@@ -257,9 +268,25 @@ jobs:
 
       - name: Install build dependencies
         run: |
+          # Bump apt's default 3 retries; papers over short upstream blips
+          # like the recurring ppa.launchpadcontent.net outages.
+          echo 'Acquire::Retries "5";' > /etc/apt/apt.conf.d/80-retries
           apt-get update
           apt-get install -y software-properties-common
           add-apt-repository ppa:ubuntu-toolchain-r/test -y
+
+          # apt.llvm.org for Clang versions newer than what Ubuntu 24.04 ships
+          # (24.04 default repos cap at clang-18). The bootstrap script adds
+          # the LLVM apt source for the requested version and runs apt-get update.
+          if [ "${{ matrix.compiler }}" = "clang" ] && [ "${{ matrix.compiler_version }}" -ge 19 ]; then
+            apt-get install -y wget gnupg lsb-release
+            wget -qO /tmp/llvm.sh https://apt.llvm.org/llvm.sh
+            chmod +x /tmp/llvm.sh
+            # `all` installs clang + libllvm + lldb + lld + the llvm-N package
+            # (which provides llvm-profdata-N / llvm-cov-N for coverage runs).
+            /tmp/llvm.sh ${{ matrix.compiler_version }} all
+          fi
+
           apt-get update
           apt-get install -y git python3 python-is-python3 pipx
           pipx ensurepath
@@ -332,10 +359,16 @@ jobs:
           pipx install "conan>=2.0,<3"
           echo "$HOME/.local/bin" >> $GITHUB_PATH
 
-          # Install gcovr for coverage jobs
+          # Install coverage tooling
           if [ "${{ matrix.job_type }}" = "coverage" ]; then
-            pipx install "gcovr>=7,<9"
             apt-get install -y curl lcov
+            if [ "${{ matrix.coverage_tool }}" = "llvm" ]; then
+              # Native LLVM source-based coverage: llvm-profdata + llvm-cov.
+              # The clang-N package doesn't pull these in; the llvm-N package does.
+              apt-get install -y "llvm-${{ matrix.compiler_version }}"
+            else
+              pipx install "gcovr>=7,<9"
+            fi
           fi
 
       - name: Check environment
@@ -348,10 +381,15 @@ jobs:
           which ${{ matrix.cxx }} && ${{ matrix.cxx }} --version || echo "${{ matrix.cxx }} not found"
           which ccache && ccache --version || echo "ccache not found"
 
-          # Check gcovr for coverage jobs
+          # Check coverage tooling
           if [ "${{ matrix.job_type }}" = "coverage" ]; then
-            which gcov && gcov --version || echo "gcov not found"
-            which gcovr && gcovr --version || echo "gcovr not found"
+            if [ "${{ matrix.coverage_tool }}" = "llvm" ]; then
+              which "llvm-profdata-${{ matrix.compiler_version }}" && "llvm-profdata-${{ matrix.compiler_version }}" --version || echo "llvm-profdata not found"
+              which "llvm-cov-${{ matrix.compiler_version }}" && "llvm-cov-${{ matrix.compiler_version }}" --version || echo "llvm-cov not found"
+            else
+              which gcov && gcov --version || echo "gcov not found"
+              which gcovr && gcovr --version || echo "gcovr not found"
+            fi
           fi
 
           echo "---- Full Environment ----"
@@ -378,6 +416,7 @@ jobs:
           cc: ${{ matrix.cc }}
           cxx: ${{ matrix.cxx }}
           stdlib: ${{ matrix.stdlib }}
+          conan_deps_cxxflags: ${{ matrix.conan_deps_cxxflags && toJson(matrix.conan_deps_cxxflags) || '{}' }}
           gha_cache_enabled: 'false' # Disable caching for self hosted runner
 
       - name: Build
@@ -410,8 +449,9 @@ jobs:
           cache_version: ${{ env.CACHE_VERSION }}
           main_branch: ${{ env.MAIN_BRANCH_NAME }}
           stdlib: ${{ matrix.stdlib }}
-          # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness
-          cmake-args: '-Dcoverage=ON -Dcoverage_format=xml -Dcoverage_test_parallelism=$(($(nproc)/2)) -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_CXX_FLAGS="-O0" -DCMAKE_C_FLAGS="-O0"'
+          # Coverage builds are slower due to instrumentation; use fewer parallel jobs to avoid flakiness.
+          # Use *_FLAGS_DEBUG so the build action's stdlib flag (e.g. -stdlib=libc++) in CMAKE_CXX_FLAGS isn't clobbered.
+          cmake-args: '-Dcoverage=ON -Dcoverage_tool=${{ matrix.coverage_tool }} -Dcoverage_format=${{ matrix.coverage_format }} -Dcoverage_test_parallelism=$(($(nproc)/2)) -DCODE_COVERAGE_VERBOSE=ON -DCMAKE_CXX_FLAGS_DEBUG="-g -O0" -DCMAKE_C_FLAGS_DEBUG="-g -O0"'
           cmake-target: 'coverage'
           ccache_max_size: '100G'
 
@@ -443,22 +483,26 @@ jobs:
       - name: Move coverage report
         if: matrix.job_type == 'coverage'
         shell: bash
+        env:
+          COVERAGE_FILE: ${{ matrix.coverage_tool == 'llvm' && 'coverage.lcov' || 'coverage.xml' }}
         run: |
-          mv "${{ env.build_dir }}/coverage.xml" ./
+          mv "${{ env.build_dir }}/${COVERAGE_FILE}" ./
+          echo "COVERAGE_FILE=${COVERAGE_FILE}" >> "$GITHUB_ENV"
 
       - name: Archive coverage report
         if: matrix.job_type == 'coverage'
         uses: actions/upload-artifact@v4
         with:
-          name: coverage.xml
-          path: coverage.xml
+          name: ${{ env.COVERAGE_FILE }}-${{ matrix.compiler_id }}
+          path: ${{ env.COVERAGE_FILE }}
           retention-days: 30
 
       - name: Upload coverage report
         if: matrix.job_type == 'coverage'
         uses: codecov/codecov-action@v5
         with:
-          files: coverage.xml
+          files: ${{ env.COVERAGE_FILE }}
+          flags: ${{ matrix.coverage_tool }}
           fail_ci_if_error: true
           disable_search: true
           verbose: true

cmake/CodeCoverageLLVM.cmake

@@ -0,0 +1,156 @@
+#[===================================================================[
+  Native LLVM source-based code coverage helper.
+
+  Drives the -fprofile-instr-generate / -fcoverage-mapping pipeline:
+    1. Run instrumented binary with LLVM_PROFILE_FILE=...%m-%p.profraw
+    2. llvm-profdata merge -sparse  -> coverage.profdata
+    3. llvm-cov export/show/report  -> final report
+
+  Output filename per coverage_format:
+    lcov              -> coverage.lcov
+    json              -> coverage.json
+    txt | text        -> coverage.txt
+    html | html-details -> <NAME>/index.html
+#]===================================================================]
+
+include(CMakeParseArguments)
+
+# Locate llvm-profdata / llvm-cov, preferring versioned variants matching the
+# Clang we're building with so we don't accidentally pair clang-20 with
+# llvm-cov-14 (profile format mismatch -> hard failure).
+function(_find_llvm_cov_tools)
+  if(LLVM_PROFDATA_PATH AND LLVM_COV_PATH)
+    return()
+  endif()
+
+  string(REGEX MATCH "^[0-9]+" _major "${CMAKE_CXX_COMPILER_VERSION}")
+
+  set(_pd_names llvm-profdata)
+  set(_cov_names llvm-cov)
+  if(_major)
+    list(PREPEND _pd_names "llvm-profdata-${_major}")
+    list(PREPEND _cov_names "llvm-cov-${_major}")
+  endif()
+
+  # Only delegate to xcrun when the *compiler* is AppleClang. On macOS with
+  # Homebrew/system clang-N, xcrun would resolve to Xcode's llvm tools which
+  # could be a different version - exactly the mismatch we want to avoid.
+  if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+    execute_process(COMMAND xcrun -f llvm-profdata
+      OUTPUT_VARIABLE _pd_xcrun OUTPUT_STRIP_TRAILING_WHITESPACE
+      ERROR_QUIET RESULT_VARIABLE _pd_rc)
+    if(_pd_rc EQUAL 0 AND _pd_xcrun)
+      set(LLVM_PROFDATA_PATH "${_pd_xcrun}" CACHE FILEPATH "llvm-profdata" FORCE)
+    endif()
+    execute_process(COMMAND xcrun -f llvm-cov
+      OUTPUT_VARIABLE _cov_xcrun OUTPUT_STRIP_TRAILING_WHITESPACE
+      ERROR_QUIET RESULT_VARIABLE _cov_rc)
+    if(_cov_rc EQUAL 0 AND _cov_xcrun)
+      set(LLVM_COV_PATH "${_cov_xcrun}" CACHE FILEPATH "llvm-cov" FORCE)
+    endif()
+  endif()
+
+  if(NOT LLVM_PROFDATA_PATH)
+    find_program(LLVM_PROFDATA_PATH NAMES ${_pd_names})
+  endif()
+  if(NOT LLVM_COV_PATH)
+    find_program(LLVM_COV_PATH NAMES ${_cov_names})
+  endif()
+endfunction()
+
+function(setup_target_for_coverage_llvm)
+  set(oneValueArgs NAME FORMAT)
+  set(multiValueArgs EXCLUDE EXECUTABLE EXECUTABLE_ARGS DEPENDENCIES)
+  cmake_parse_arguments(Cov "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  _find_llvm_cov_tools()
+  if(NOT LLVM_PROFDATA_PATH)
+    message(FATAL_ERROR "llvm-profdata not found (needed for coverage_tool=llvm)")
+  endif()
+  if(NOT LLVM_COV_PATH)
+    message(FATAL_ERROR "llvm-cov not found (needed for coverage_tool=llvm)")
+  endif()
+
+  if(NOT Cov_FORMAT)
+    set(Cov_FORMAT lcov)
+  endif()
+
+  set(_profraw_dir "${PROJECT_BINARY_DIR}/${Cov_NAME}-profraw")
+  set(_profdata    "${PROJECT_BINARY_DIR}/${Cov_NAME}.profdata")
+
+  # Resolve binary path: accept either an absolute path or a bare target name
+  # (resolved against PROJECT_BINARY_DIR). Splice the resolved path back into
+  # Cov_EXECUTABLE so the run command invokes it via absolute path - bare
+  # names aren't on PATH and the build dir isn't `.` either.
+  list(GET Cov_EXECUTABLE 0 _exec_name)
+  if(IS_ABSOLUTE "${_exec_name}")
+    set(_binary "${_exec_name}")
+  else()
+    set(_binary "${PROJECT_BINARY_DIR}/${_exec_name}")
+    list(REMOVE_AT Cov_EXECUTABLE 0)
+    list(PREPEND Cov_EXECUTABLE "${_binary}")
+  endif()
+
+  # llvm-cov takes a single -ignore-filename-regex; OR our excludes together.
+  set(_ignore_regex "")
+  foreach(EXC IN LISTS Cov_EXCLUDE)
+    if(_ignore_regex)
+      string(APPEND _ignore_regex "|")
+    endif()
+    string(APPEND _ignore_regex "${EXC}")
+  endforeach()
+  set(_filter "")
+  if(_ignore_regex)
+    set(_filter "-ignore-filename-regex='${_ignore_regex}'")
+  endif()
+
+  # Pick llvm-cov subcommand + output file for the requested format. Each
+  # branch builds a single shell command string that we'll hand to bash -c.
+  if(Cov_FORMAT STREQUAL "lcov")
+    set(_output "${PROJECT_BINARY_DIR}/coverage.lcov")
+    set(_report_sh "${LLVM_COV_PATH} export -instr-profile='${_profdata}' -format=lcov ${_filter} '${_binary}' > '${_output}'")
+  elseif(Cov_FORMAT STREQUAL "json")
+    set(_output "${PROJECT_BINARY_DIR}/coverage.json")
+    set(_report_sh "${LLVM_COV_PATH} export -instr-profile='${_profdata}' -format=text ${_filter} '${_binary}' > '${_output}'")
+  elseif(Cov_FORMAT STREQUAL "txt" OR Cov_FORMAT STREQUAL "text")
+    set(_output "${PROJECT_BINARY_DIR}/coverage.txt")
+    set(_report_sh "${LLVM_COV_PATH} report -instr-profile='${_profdata}' ${_filter} '${_binary}' > '${_output}'")
+  elseif(Cov_FORMAT STREQUAL "html" OR Cov_FORMAT STREQUAL "html-details")
+    set(_output "${PROJECT_BINARY_DIR}/${Cov_NAME}/index.html")
+    set(_report_sh "${LLVM_COV_PATH} show -instr-profile='${_profdata}' -format=html -output-dir='${PROJECT_BINARY_DIR}/${Cov_NAME}' ${_filter} '${_binary}'")
+  else()
+    message(FATAL_ERROR "coverage_tool=llvm: unsupported coverage_format '${Cov_FORMAT}' (use lcov|json|txt|html)")
+  endif()
+
+  set(_merge_sh "${LLVM_PROFDATA_PATH} merge -sparse -o '${_profdata}' '${_profraw_dir}'/*.profraw")
+
+  if(CODE_COVERAGE_VERBOSE)
+    message(STATUS "[coverage:llvm] binary:   ${_binary}")
+    message(STATUS "[coverage:llvm] profraw:  ${_profraw_dir}")
+    message(STATUS "[coverage:llvm] profdata: ${_profdata}")
+    message(STATUS "[coverage:llvm] format:   ${Cov_FORMAT}")
+    message(STATUS "[coverage:llvm] output:   ${_output}")
+    if(_ignore_regex)
+      message(STATUS "[coverage:llvm] ignore:   ${_ignore_regex}")
+    endif()
+    message(STATUS "[coverage:llvm] merge:    ${_merge_sh}")
+    message(STATUS "[coverage:llvm] report:   ${_report_sh}")
+  endif()
+
+  # %m: hash of the binary, %p: pid. Wipe the dir up front so stale profraw
+  # files can't leak into a fresh merge.
+  add_custom_target(${Cov_NAME}
+    COMMAND ${CMAKE_COMMAND} -E rm -rf "${_profraw_dir}"
+    COMMAND ${CMAKE_COMMAND} -E make_directory "${_profraw_dir}"
+    COMMAND ${CMAKE_COMMAND} -E env
+        "LLVM_PROFILE_FILE=${_profraw_dir}/rippled-%m-%p.profraw"
+        ${Cov_EXECUTABLE} ${Cov_EXECUTABLE_ARGS}
+    COMMAND bash -c "${_merge_sh}"
+    COMMAND bash -c "${_report_sh}"
+    BYPRODUCTS ${_output}
+    WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+    DEPENDS ${Cov_DEPENDENCIES}
+    VERBATIM
+    COMMENT "Running llvm-cov (${Cov_FORMAT}) -> ${_output}"
+  )
+endfunction()

cmake/RippledCov.cmake

@@ -11,6 +11,21 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
   return()
 endif()
 
+if(coverage_tool STREQUAL "llvm")
+  include(CodeCoverageLLVM)
+
+  setup_target_for_coverage_llvm(
+    NAME coverage
+    FORMAT ${coverage_format}
+    EXECUTABLE rippled
+    EXECUTABLE_ARGS --unittest$<$<BOOL:${coverage_test}>:=${coverage_test}> --unittest-jobs ${coverage_test_parallelism} --quiet --unittest-log
+    EXCLUDE "src/test" "include/xrpl/beast/test" "include/xrpl/beast/unit_test" "${CMAKE_BINARY_DIR}/pb-xrpl.libpb"
+    DEPENDENCIES rippled
+  )
+  return()
+endif()
+
+# coverage_tool == "gcov" (default): existing gcovr-driven pipeline.
 include(CodeCoverage)
 
 # The instructions for these commands come from the `CodeCoverage` module,

cmake/RippledInterface.cmake

@@ -28,15 +28,17 @@ target_compile_options (opts
     $<$<AND:$<BOOL:${is_gcc}>,$<COMPILE_LANGUAGE:CXX>>:-Wsuggest-override>
     $<$<BOOL:${is_gcc}>:-Wno-maybe-uninitialized>
     $<$<BOOL:${perf}>:-fno-omit-frame-pointer>
-    $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${coverage}>>:-g --coverage -fprofile-abs-path>
-    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>>:-g --coverage>
+    $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},gcov>>:-g --coverage -fprofile-abs-path>
+    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},gcov>>:-g --coverage>
+    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},llvm>>:-g -fprofile-instr-generate -fcoverage-mapping>
     $<$<BOOL:${profile}>:-pg>
     $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>)
 
 target_link_libraries (opts
   INTERFACE
-    $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${coverage}>>:-g --coverage -fprofile-abs-path>
-    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>>:-g --coverage>
+    $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},gcov>>:-g --coverage -fprofile-abs-path>
+    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},gcov>>:-g --coverage>
+    $<$<AND:$<BOOL:${is_clang}>,$<BOOL:${coverage}>,$<STREQUAL:${coverage_tool},llvm>>:-g -fprofile-instr-generate -fcoverage-mapping>
     $<$<BOOL:${profile}>:-pg>
     $<$<AND:$<BOOL:${is_gcc}>,$<BOOL:${profile}>>:-p>)
 

cmake/RippledSettings.cmake

@@ -29,13 +29,25 @@ if(is_gcc OR is_clang)
     "Unit tests parallelism for the purpose of coverage report.")
   set(coverage_format "html-details" CACHE STRING
     "Output format of the coverage report.")
+  set(coverage_tool "gcov" CACHE STRING
+    "Coverage instrumentation tool: 'gcov' (default, gcc/clang via --coverage + gcovr) or 'llvm' (clang only, native source-based coverage via -fprofile-instr-generate).")
+  set_property(CACHE coverage_tool PROPERTY STRINGS "gcov" "llvm")
+  if(NOT coverage_tool MATCHES "^(gcov|llvm)$")
+    message(FATAL_ERROR "coverage_tool must be 'gcov' or 'llvm', got '${coverage_tool}'")
+  endif()
   set(coverage_extra_args "" CACHE STRING
-    "Additional arguments to pass to gcovr.")
+    "Additional arguments to pass to gcovr (gcov tool only).")
   set(coverage_test "" CACHE STRING
     "On gcc & clang, the specific unit test(s) to run for coverage. Default is all tests.")
   if(coverage_test AND NOT coverage)
     set(coverage ON CACHE BOOL "gcc/clang only" FORCE)
   endif()
+  # Validate after coverage_test may have flipped coverage on, otherwise
+  # `-Dcoverage_tool=llvm -Dcoverage_test=Foo` on gcc would silently slip
+  # past the Clang guard and produce a broken instrumentation combo.
+  if(coverage AND coverage_tool STREQUAL "llvm" AND NOT is_clang)
+    message(FATAL_ERROR "coverage_tool=llvm requires Clang (got ${CMAKE_CXX_COMPILER_ID})")
+  endif()
   option(wextra "compile with extra gcc/clang warnings enabled" ON)
 else()
   set(profile OFF CACHE BOOL "gcc/clang only" FORCE)