doc: develop: sca: Update CodeChecker configuration options

Put CodeChecker configuration parameters in tables for a clear overview
of all the options.

Signed-off-by: Pieter De Gendt <pieter.degendt@basalte.be>

doc/develop/sca/codechecker.rst

@@ -19,8 +19,8 @@ CodeChecker itself is a python package available on `pypi <https://pypi.org/proj
 
     pip install codechecker
 
-Running with CodeChecker
+Building with CodeChecker
-************************
+*************************
 
 To run CodeChecker, :ref:`west build <west-building>` should be
 called with a ``-DZEPHYR_SCA_VARIANT=codechecker`` parameter, e.g.
@@ -33,56 +33,63 @@ called with a ``-DZEPHYR_SCA_VARIANT=codechecker`` parameter, e.g.
 Configuring CodeChecker
 ***********************
 
-To configure CodeChecker or analyzers used, arguments can be passed using the
+CodeChecker uses different command steps, each with their respective configuration
-``CODECHECKER_ANALYZE_OPTS`` parameter, e.g.
+parameters. The following table lists all these options.
-
+
-.. code-block:: shell
+.. list-table::
-
+   :header-rows: 1
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
+
-    -DCODECHECKER_ANALYZE_OPTS="--config;$CODECHECKER_CONFIG_FILE;--timeout;60"
+   * - Parameter
-
+     - Description
-
+   * - ``CODECHECKER_ANALYZE_JOBS``
-Storing CodeChecker results
+     - The number of threads to use in analysis. (default: <CPU count>)
-***************************
+   * - ``CODECHECKER_ANALYZE_OPTS``
-
+     - Arguments passed to the ``analyze`` command directly. (e.g. ``--timeout;360``)
-If a CodeChecker server is active the results can be uploaded and stored for tracking purposes.
+   * - ``CODECHECKER_CLEANUP``
-Storing is done using the optional ``CODECHECKER_STORE=y`` or ``CODECHECKER_STORE_OPTS="arg;list"``
+     - Perform a cleanup after parsing/storing. This will remove all ``plist`` files.
-parameters, e.g.
+   * - ``CODECHECKER_CONFIG_FILE``
-
+     - A JSON or YAML file with configuration options passed to all commands.
-.. code-block:: shell
+   * - ``CODECHECKER_EXPORT``
-
+     - A comma separated list of report types. Allowed types are:
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
+       ``html,json,codeclimate,gerrit,baseline``.
-    -DCODECHECKER_STORE_OPTS="--name;build;--url;localhost:8001/Default"
+   * - ``CODECHECKER_NAME``
-
+     - The CodeChecker run metadata name. (default: ``zephyr``)
-.. note::
+   * - ``CODECHECKER_PARSE_EXIT_STATUS``
-
+     - By default, CodeChecker identified issues will not fail the build, set this option to fail
-    If ``--name`` isn't passed to either ``CODECHECKER_ANALYZE_OPTS`` or ``CODECHECKER_STORE_OPTS``,
+       during analysis.
-    the default ``zephyr`` is used.
+   * - ``CODECHECKER_PARSE_OPTS``
-
+     - Arguments passed to the ``parse`` command directly. (e.g. ``--verbose;debug``)
-
+   * - ``CODECHECKER_PARSE_SKIP``
-Exporting CodeChecker reports
+     - Skip parsing the analysis, useful if you simply want to store the results.
-*****************************
+   * - ``CODECHECKER_STORE``
-
+     - Run the ``store`` command after analysis.
-Optional reports can be generated using the CodeChecker results, when passing a
+   * - ``CODECHECKER_STORE_OPTS``
-``-DCODECHECKER_EXPORT=<type>`` parameter. Allowed types are: ``html,json,codeclimate,gerrit,baseline``.
+     - Arguments passed to the ``store`` command directly. Implies ``CODECHECKER_STORE``.
-Multiple types can be passed as comma-separated arguments.
+       (e.g. ``--url;localhost:8001/Default``)
-
+   * - ``CODECHECKER_STORE_TAG``
-Optional parser configuration arguments can be passed using the
+     - Pass an identifier ``--tag`` to the ``store`` command.
-``CODECHECKER_PARSE_OPTS`` parameter, e.g.
+   * - ``CODECHECKER_TRIM_PATH_PREFIX``
-
+     - Trim the defined path from the analysis results, e.g. ``/home/user/zephyrproject``.
-.. code-block:: shell
+       The value from ``west topdir`` is added by default.
-
+
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
+These parameters can be passed on the command line, or be set as environment variables.
-    -DCODECHECKER_EXPORT=html,json -DCODECHECKER_PARSE_OPTS="--trim-path-prefix;$PWD"
+
-
+
-Failing the build on CodeChecker issues
+Running twister with CodeChecker
-***************************************
+********************************
-
+
-By default, CodeChecker identified issues will not fail the build, only generate
+When running CodeChecker as part of ``twister`` some default options are set as following:
-a report. To fail the build if any issues are found (for example, for use in
+
-CI), pass the ``CODECHECKER_PARSE_EXIT_STATUS=y`` parameter, e.g.
+.. list-table::
-
+   :header-rows: 1
-.. code-block:: shell
+
-
+   * - Parameter
-    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \
+     - Value
-    -DCODECHECKER_PARSE_EXIT_STATUS=y
+   * - ``CODECHECKER_ANALYZE_JOBS``
+     - ``1``
+   * - ``CODECHECKER_NAME``
+     - ``<board target>:<testsuite name>``
+   * - ``CODECHECKER_STORE_TAG``
+     - The value from ``git describe`` in the application source directory.
+
+To override these values, set an environment variable or pass them as extra arguments.