Add documentation and flags for generating code coverage report (#8959)

CMakeLists.txt

@@ -41,6 +41,8 @@ option(FILAMENT_ENABLE_ASAN_UBSAN "Enable Address and Undefined Behavior Sanitiz
 
 option(FILAMENT_ENABLE_TSAN "Enable Thread Sanitizer" OFF)
 
+option(FILAMENT_ENABLE_COVERAGE "Enable LLVM code coverage" OFF)
+
 option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)
 
 option(FILAMENT_ENABLE_MULTIVIEW "Enable multiview for Filament" OFF)
@@ -460,6 +462,10 @@ if (NOT MSVC AND NOT WEBGL)
 endif()
 set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${EXTRA_SANITIZE_OPTIONS}")
 
+if (FILAMENT_ENABLE_COVERAGE)
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fprofile-instr-generate -fcoverage-mapping")
+endif()
+
 # Disable the stack check for macOS to workaround a known issue in clang 11.0.0.
 # See: https://forums.developer.apple.com/thread/121887
 if (APPLE)

build.sh

@@ -63,6 +63,9 @@ function print_help {
     echo "    -b"
     echo "        Enable Address and Undefined Behavior Sanitizers (asan/ubsan) for debugging."
     echo "        This is only for the desktop build."
+    echo "    -V"
+    echo "        Enable LLVM code coverage for debug builds."
+    echo "        This is only for the desktop build."
     echo "    -x value"
     echo "        Define a preprocessor flag FILAMENT_BACKEND_DEBUG_FLAG with [value]. This is useful for"
     echo "        enabling debug paths in the backend from the build script. For example, make a"
@@ -208,6 +211,7 @@ MATOPT_OPTION=""
 MATOPT_GRADLE_OPTION=""
 
 ASAN_UBSAN_OPTION=""
+COVERAGE_OPTION=""
 
 BACKEND_DEBUG_FLAG_OPTION=""
 
@@ -275,6 +279,7 @@ function build_desktop_target {
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${ASAN_UBSAN_OPTION} \
+            ${COVERAGE_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
             ${STEREOSCOPIC_OPTION} \
             ${OSMESA_OPTION} \
@@ -835,7 +840,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgimp:q:uvWslwedtk:bx:S:X:" opt; do
+while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:" opt; do
     case ${opt} in
         h)
             print_help
@@ -983,6 +988,9 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bx:S:X:" opt; do
         b)  ASAN_UBSAN_OPTION="-DFILAMENT_ENABLE_ASAN_UBSAN=ON"
             echo "Enabled ASAN/UBSAN"
             ;;
+        V)  COVERAGE_OPTION="-DFILAMENT_ENABLE_COVERAGE=ON"
+            echo "Enabled coverage"
+            ;;
         x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
             ;;
         S)  case $(echo "${OPTARG}" | tr '[:upper:]' '[:lower:]') in

docs_src/src_mdbook/src/notes/coverage.md

@@ -0,0 +1,114 @@
+# Generating Backend Code Coverage
+
+Code coverage analysis helps visualize which parts of the backend are exercised by backend tests.
+This guide outlines the process for generating an HTML coverage report for Filament's backend on
+macOS.
+
+## 1\. Prerequisites: Install Clang and LLVM tools
+
+You'll need a recent version of **Clang** and its corresponding **LLVM tools** for code coverage.
+You can install these using Homebrew or MacPorts.
+
+### Using Homebrew
+
+Install the `llvm` package:
+
+```bash
+brew install llvm
+```
+
+This typically installs the tools in a location like `/usr/local/opt/llvm/bin`. You may need to add
+this to your `PATH` environment variable.
+
+### Using MacPorts
+
+Install a specific version of Clang (e.g., version 18):
+
+```bash
+sudo port install clang-18
+```
+
+MacPorts often adds version suffixes to the tool names (e.g., `llvm-cov-mp-18`).
+
+### Required Tools
+
+Ensure you can locate the following tools from your installation:
+
+  * `clang` and `clang++` (The C/C++ compilers)
+  * `llvm-profdata` (For merging coverage data)
+  * `llvm-cov` (For generating reports)
+
+The rest of this guide assumes your tools are in your `PATH`. If not, you'll need to use the full
+path to each executable.
+
+## 2\. Build Filament with Coverage Enabled
+
+Compile the `backend_test_mac` target with coverage instrumentation. This is done by setting the
+`CC` and `CXX` environment variables to point to your Clang compiler and using the `-V` flag in the
+build script.
+
+```bash
+CC=clang CXX=clang++ ./build.sh -V -p desktop debug backend_test_mac
+```
+
+*If your Clang executables aren't in your `PATH` or have version suffixes, provide the full name or
+path (e.g., `CC=/opt/local/bin/clang CXX=/opt/local/bin/clang++`).*
+
+## 3\. Run the Backend Tests
+
+Running the test suite will generate the raw coverage data needed for the report.
+
+1.  Navigate to the build output directory:
+
+    ```bash
+    cd out/cmake-debug/filament/backend
+    ```
+
+2.  Run the tests for a specific backend (e.g., Metal):
+
+    ```bash
+    ./backend_test_mac --api metal
+    ```
+
+This command creates a `default.profraw` file in the current directory, which contains the raw
+execution profile data.
+
+## 4\. Generate the Coverage Report
+
+Finally, process the raw data and generate an HTML report.
+
+1.  **Merge the raw profile data** into a single file using `llvm-profdata`.
+
+    ```bash
+    llvm-profdata merge -sparse default.profraw -o filament.profdata
+    ```
+
+    *Remember to use the version-specific tool name if required (e.g., `llvm-profdata-mp-18`).*
+
+2.  **Generate the HTML report** using `llvm-cov`. This command creates a report for the entire
+    `backend_test_mac` executable.
+
+    ```bash
+    llvm-cov show ./backend_test_mac \
+      -instr-profile=filament.profdata \
+      -format=html \
+      -show-line-counts-or-regions > coverage.html
+    ```
+
+    *To view coverage for a **specific source file**, add its path at the end of the command:*
+
+    ```bash
+    llvm-cov show ./backend_test_mac \
+      -instr-profile=filament.profdata \
+      -format=html \
+      -show-line-counts-or-regions \
+      -- ../../../../filament/backend/src/metal/MetalDriver.mm > coverage.html
+    ```
+
+3.  **Open the report** in your browser:
+
+    ```bash
+    open coverage.html
+    ```
+
+In the report, code paths that were not executed during the test run will be highlighted in red.