From 493cc9daeabcc064b937ab365a4717d74657d26a Mon Sep 17 00:00:00 2001 From: Pieter De Gendt Date: Mon, 26 Aug 2024 21:01:12 +0200 Subject: [PATCH] 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 --- doc/develop/sca/codechecker.rst | 117 +++++++++++++++++--------------- 1 file changed, 62 insertions(+), 55 deletions(-) diff --git a/doc/develop/sca/codechecker.rst b/doc/develop/sca/codechecker.rst index 985a55283f4..8b793ad5dcd 100644 --- a/doc/develop/sca/codechecker.rst +++ b/doc/develop/sca/codechecker.rst @@ -19,8 +19,8 @@ CodeChecker itself is a python package available on `pypi ` 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_ANALYZE_OPTS`` parameter, e.g. - -.. code-block:: shell - - west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \ - -DCODECHECKER_ANALYZE_OPTS="--config;$CODECHECKER_CONFIG_FILE;--timeout;60" - - -Storing CodeChecker results -*************************** - -If a CodeChecker server is active the results can be uploaded and stored for tracking purposes. -Storing is done using the optional ``CODECHECKER_STORE=y`` or ``CODECHECKER_STORE_OPTS="arg;list"`` -parameters, e.g. - -.. code-block:: shell - - west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \ - -DCODECHECKER_STORE_OPTS="--name;build;--url;localhost:8001/Default" - -.. note:: - - If ``--name`` isn't passed to either ``CODECHECKER_ANALYZE_OPTS`` or ``CODECHECKER_STORE_OPTS``, - the default ``zephyr`` is used. - - -Exporting CodeChecker reports -***************************** - -Optional reports can be generated using the CodeChecker results, when passing a -``-DCODECHECKER_EXPORT=`` parameter. Allowed types are: ``html,json,codeclimate,gerrit,baseline``. -Multiple types can be passed as comma-separated arguments. - -Optional parser configuration arguments can be passed using the -``CODECHECKER_PARSE_OPTS`` parameter, e.g. - -.. code-block:: shell - - west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \ - -DCODECHECKER_EXPORT=html,json -DCODECHECKER_PARSE_OPTS="--trim-path-prefix;$PWD" - -Failing the build on CodeChecker issues -*************************************** - -By default, CodeChecker identified issues will not fail the build, only generate -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. - -.. code-block:: shell - - west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=codechecker \ - -DCODECHECKER_PARSE_EXIT_STATUS=y +CodeChecker uses different command steps, each with their respective configuration +parameters. The following table lists all these options. + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Description + * - ``CODECHECKER_ANALYZE_JOBS`` + - The number of threads to use in analysis. (default: ) + * - ``CODECHECKER_ANALYZE_OPTS`` + - Arguments passed to the ``analyze`` command directly. (e.g. ``--timeout;360``) + * - ``CODECHECKER_CLEANUP`` + - Perform a cleanup after parsing/storing. This will remove all ``plist`` files. + * - ``CODECHECKER_CONFIG_FILE`` + - A JSON or YAML file with configuration options passed to all commands. + * - ``CODECHECKER_EXPORT`` + - A comma separated list of report types. Allowed types are: + ``html,json,codeclimate,gerrit,baseline``. + * - ``CODECHECKER_NAME`` + - The CodeChecker run metadata name. (default: ``zephyr``) + * - ``CODECHECKER_PARSE_EXIT_STATUS`` + - By default, CodeChecker identified issues will not fail the build, set this option to fail + during analysis. + * - ``CODECHECKER_PARSE_OPTS`` + - Arguments passed to the ``parse`` command directly. (e.g. ``--verbose;debug``) + * - ``CODECHECKER_PARSE_SKIP`` + - Skip parsing the analysis, useful if you simply want to store the results. + * - ``CODECHECKER_STORE`` + - Run the ``store`` command after analysis. + * - ``CODECHECKER_STORE_OPTS`` + - Arguments passed to the ``store`` command directly. Implies ``CODECHECKER_STORE``. + (e.g. ``--url;localhost:8001/Default``) + * - ``CODECHECKER_STORE_TAG`` + - Pass an identifier ``--tag`` to the ``store`` command. + * - ``CODECHECKER_TRIM_PATH_PREFIX`` + - Trim the defined path from the analysis results, e.g. ``/home/user/zephyrproject``. + The value from ``west topdir`` is added by default. + +These parameters can be passed on the command line, or be set as environment variables. + + +Running twister with CodeChecker +******************************** + +When running CodeChecker as part of ``twister`` some default options are set as following: + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Value + * - ``CODECHECKER_ANALYZE_JOBS`` + - ``1`` + * - ``CODECHECKER_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.