sca: gcc: add support for additional analyzer options

This commit brings support for additional GCC static analyzer options
with 'GCC_SCA_OPTS=...'

Linked to discussion on 'ccache' side effect on analyzer file
generation[1]

[1] #86196

Signed-off-by: Alex Fabre <[email protected]>

cmake/sca/gcc/sca.cmake

@@ -1,5 +1,36 @@
 # SPDX-License-Identifier: Apache-2.0
 #
 # Copyright (c) 2024 Intel Corporation
+# Copyright (c) 2025 Alex Fabre
 
+# Check GCC version
+# GCC static analyzer requires GCC version >= 10.0.0
+if("${GCC_COMPILER_VERSION}" VERSION_LESS 10.0.0)
+  message(FATAL_ERROR "GCC static analyzer requires GCC >= v10.0")
+endif()
+
+
+# Enable GCC static analyzer
 list(APPEND TOOLCHAIN_C_FLAGS -fanalyzer)
+
+# Add GCC analyzer user options
+zephyr_get(GCC_SCA_OPTS)
+zephyr_get(USE_CCACHE)
+
+if(DEFINED GCC_SCA_OPTS)
+  foreach(analyzer_option IN LISTS GCC_SCA_OPTS)
+
+    if(analyzer_option STREQUAL "-fdiagnostics-format=sarif-file" OR analyzer_option STREQUAL "-fdiagnostics-format=json-file")
+      # Beginning with GCC 14, users can use the -fdiagnostics-format option
+      # to output analyzer diagnostics as SARIF or JSON files.
+      # This option encounters a specific issue[1] when used with ccache.
+      # Therefore, currently, the build process is halted if 'ccache' is enabled.
+      # [1] https://github.com/ccache/ccache/issues/1466
+      if(NOT USE_CCACHE STREQUAL "0")
+        message(FATAL_ERROR "GCC SCA requires 'ccache' to be disabled for output file generation. Disable 'ccache' by setting USE_CCACHE=0.")
+      endif()
+    endif()
+
+    list(APPEND TOOLCHAIN_C_FLAGS ${analyzer_option})
+  endforeach()
+endif()

doc/develop/sca/gcc.rst

@@ -13,6 +13,58 @@ Run GCC static analysis
 To run GCC static analysis, :ref:`west build <west-building>` should be
 called with a ``-DZEPHYR_SCA_VARIANT=gcc`` parameter, e.g.
 
-.. code-block:: shell
+.. zephyr-app-commands::
+   :zephyr-app: samples/userspace/hello_world_user
+   :board: qemu_x86
+   :gen-args: -DZEPHYR_SCA_VARIANT=gcc
+   :goals: build
+   :compact:
 
-    west build -b qemu_x86 samples/userspace/hello_world_user -- -DZEPHYR_SCA_VARIANT=gcc
+Configuring GCC static analyzer
+*******************************
+
+GCC static analyzer can be controlled using specific options.
+
+* `Options controlling the
+  analyzer <https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html>`__
+* `Options controlling the diagnostic message
+  formatting <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html>`__
+
+.. list-table::
+   :header-rows: 1
+
+   * - Parameter
+     - Description
+   * - ``GCC_SCA_OPTS``
+     - A semicolon separated list of GCC analyzer options.
+
+These parameters can be passed on the command line, or be set as environment variables.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :board: stm32h573i_dk
+   :gen-args: -DZEPHYR_SCA_VARIANT=gcc -DGCC_SCA_OPTS="-fdiagnostics-format=json;-fanalyzer-verbosity=3"
+   :goals: build
+   :compact:
+
+.. note::
+
+   GCC static analyzer is under active development, and each new release comes with new options.
+   This `page <https://gcc.gnu.org/wiki/StaticAnalyzer>`__ gives an overview of options and fix
+   introduced with each new release of the analyzer.
+
+
+Latest version of the analyzer
+******************************
+
+Since the Zephyr toolchain may not include the most recent version of the GCC static analyzer,
+the GCC static analysis can be run with a more recent `GNU Arm embedded toolchain
+<https://docs.zephyrproject.org/latest/develop/toolchains/gnu_arm_embedded.html>`__
+to take advantage of the latest analyzer version.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/hello_world
+   :board: stm32h573i_dk
+   :gen-args: -DZEPHYR_SCA_VARIANT=gcc -DZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb -DGNUARMEMB_TOOLCHAIN_PATH=...
+   :goals: build
+   :compact: