doc: update ECLAIR documentation

Added prerequisites section, fixed some typos and added ECLAIR_RULESET_ZEPHYR_GUIDELINES option. Also updated dead doc string links in ECLAIR configuration files. Signed-off-by: Luca Ciucci <luca.ciucci@bugseng.com>
2025-05-02 10:19:57 +02:00 · 2025-05-02 10:19:57 +02:00 · d8b86f1ac7
commit d8b86f1ac7
parent c56a8049ed
7 changed files with 51 additions and 35 deletions
--- a/cmake/sca/eclair/ECL/analysis_STU.ecl
+++ b/cmake/sca/eclair/ECL/analysis_STU.ecl
@ -9,7 +9,7 @@
 -eval_file=zephyr_common_config.ecl

 -doc_begin="Selection of guidelines from
-https://docs.zephyrproject.org/latest/guides/coding_guidelines/index.html"
+https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.D4.13
 -enable=MC3R1.D4.2
 -enable=MC3R1.D4.4
--- a/cmake/sca/eclair/ECL/analysis_WP.ecl
+++ b/cmake/sca/eclair/ECL/analysis_WP.ecl
@ -9,7 +9,7 @@
 -eval_file=zephyr_common_config.ecl

 -doc_begin="Selection of guidelines from
-https://docs.zephyrproject.org/latest/guides/coding_guidelines/index.html"
+https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.R2.3
 -enable=MC3R1.R2.1
 -enable=MC3R1.R5.9
--- a/cmake/sca/eclair/ECL/analysis_first_analysis.ecl
+++ b/cmake/sca/eclair/ECL/analysis_first_analysis.ecl
@ -9,7 +9,7 @@
 -eval_file=zephyr_common_config.ecl

 -doc_begin="Selection of guidelines from
-https://docs.zephyrproject.org/latest/guides/coding_guidelines/index.html"
+https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.R8.2
 -enable=MC3R1.R10.2
 -enable=MC3R1.R10.5
--- a/cmake/sca/eclair/ECL/analysis_heavy_STU.ecl
+++ b/cmake/sca/eclair/ECL/analysis_heavy_STU.ecl
@ -9,7 +9,7 @@
 -eval_file=zephyr_common_config.ecl

 -doc_begin="Selection of guidelines from
-https://docs.zephyrproject.org/latest/guides/coding_guidelines/index.html"
+https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.D4.6
 -enable=MC3R1.D4.9
 -enable=MC3R1.R12.1
--- a/cmake/sca/eclair/ECL/analysis_std_lib.ecl
+++ b/cmake/sca/eclair/ECL/analysis_std_lib.ecl
@ -8,7 +8,7 @@
 -eval_file=zephyr_common_config.ecl

 -doc_begin="Selection of guidelines from
-https://docs.zephyrproject.org/latest/guides/coding_guidelines/index.html"
+https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.R21.1
 -enable=MC3R1.R21.12
 -enable=MC3R1.R21.14
--- a/cmake/sca/eclair/ECL/analysis_zephyr_guidelines.ecl
+++ b/cmake/sca/eclair/ECL/analysis_zephyr_guidelines.ecl
@ -7,7 +7,7 @@
 # they may be adapted of course.
 -eval_file=zephyr_common_config.ecl

-doc_begin="Selection of guidelines from
+-doc_begin="Main rules from
 https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html"
 -enable=MC3R1.D1.1
 -enable=MC3R1.D2.1
--- a/doc/develop/sca/eclair.rst
+++ b/doc/develop/sca/eclair.rst
@ -11,10 +11,20 @@ computation of software metrics, to the checking of independence and
 freedom from interference among software components, to the automatic
 detection of important classes of software errors.

-.. important::
+Prerequisites
+*************

-   ECLAIR is a commercial tool, and it is not free software.
-   You need to have a valid license to use it.
+The ECLAIR tool must be installed and made available in the operating system's
+PATH variable.
+
+To verify the installation, you can run:
+
+.. code-block:: shell
+
+   eclair -version
+
+A valid license or trial license is required to use ECLAIR. To request a trial
+license, visit `this page <https://www.bugseng.com/eclair/free-trial>`__.

 Running ECLAIR
 **************
@ -34,21 +44,23 @@ called with a ``-DZEPHYR_SCA_VARIANT=eclair`` parameter.
 Configurations
 **************

-The configure of the ECLAIR SCA environment can either be done via a cmake options file or with
-adapted options as command line arguments.
+The configuration of the ECLAIR SCA environment can either be done via a CMake
+options file or with adapted options as command line arguments.

-To invoke a cmake options file into the ECLAIR call, you can define the ``ECLAIR_OPTIONS_FILE``
-variable, for example:
+To invoke a CMake options file into the ECLAIR call, you can define the
+``ECLAIR_OPTIONS_FILE`` variable, for example:

 .. code-block:: shell

    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_OPTIONS_FILE=my_options.cmake

-The default (if no config file is given) configuration is always ``first_analysis``,
-which is a tiny selection of rules to verify that everything is correctly working.
+The default (if no config file is given) configuration is always
+``first_analysis``, which is a tiny selection of rules to verify that
+everything is correctly working.

-If the default configuration wants to be overwritten via the command line and not via a options
-file, that can be achived by giving the argument ``-DOption=ON|OFF``.
+If the default configuration wants to be overwritten via the command line and
+not via an options file, that can be achieved by giving the argument
+``-DOption=ON|OFF``.

 For example:

@ -56,15 +68,15 @@ For example:

    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_REPORTS_SARIF=ON

-Zephyr is a large and complex project, so the configuration sets are split the
-Zephyr's guidelines selection
+Zephyr is a large and complex project, so the configuration sets are split into
+the Zephyr's guidelines selection
 (taken from https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html)
 in five sets to make it more digestible to use on a private machine:

-* first_analysis (default): a tiny selection of the projects coding guidelines to verify that
+* first_analysis (default): a tiny selection of the project's coding guidelines to verify that
  everything is correctly working.

-* STU: Selection of the projects coding guidelines, which can be verified by analysing the single
+* STU: Selection of the project's coding guidelines, which can be verified by analyzing the single
  translation units independently.

 * STU_heavy: Selection of complex STU project coding guidelines that require a significant amount
@ -74,27 +86,31 @@ in five sets to make it more digestible to use on a private machine:

 * std_lib: Project coding guidelines about the C Standard Library.

-Related cmake options:
+In addition, the zephyr_guidelines ruleset contains all the main rules
+listed in the `Coding Guidelines <https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html>`__.
+
+Related CMake options:

 * ``ECLAIR_RULESET_FIRST_ANALYSIS``
 * ``ECLAIR_RULESET_STU``
 * ``ECLAIR_RULESET_STU_HEAVY``
 * ``ECLAIR_RULESET_WP``
 * ``ECLAIR_RULESET_STD_LIB``
+* ``ECLAIR_RULESET_ZEPHYR_GUIDELINES``

-User defined ruleset
+User-defined ruleset
 ====================

-If you want to use your own defined ruleset instead of the predefined zephyr coding guidelines
-rulesets. You can do so by setting :code:`ECLAIR_RULESET_USER=ON`.
-Created your own rulset file for ECLAIR with the following naming format:
-``analysis_<RULESET>.ecl``. After creating the file define the name of the ruleset for ECLAIR
-with the cmake variable :code:`ECLAIR_USER_RULESET_NAME`.
+If you want to use your own defined ruleset instead of the predefined Zephyr coding guidelines
+rulesets, you can do so by setting :code:`ECLAIR_RULESET_USER=ON`.
+Create your own ruleset file for ECLAIR with the following naming format:
+``analysis_<RULESET>.ecl``. After creating the file, define the name of the ruleset for ECLAIR
+with the CMake variable :code:`ECLAIR_USER_RULESET_NAME`.
 If the ruleset file is not in the application source directory, you can define the path to the
-ruleset file with the cmake variable :code:`ECLAIR_USER_RULESET_PATH`. This configuration takes
+ruleset file with the CMake variable :code:`ECLAIR_USER_RULESET_PATH`. This configuration takes
 relative paths and absolute paths.

-Related cmake options and variables:
+Related CMake options and variables:

 * ``ECLAIR_RULESET_USER``
 * ``ECLAIR_USER_RULESET_NAME``
@ -103,8 +119,8 @@ Related cmake options and variables:
 Generate additional report formats
 **********************************

-ECLAIR can generate additional report formats (e.g. DOC, ODT, XLSX) and
-different variants of repots in addition to the
+ECLAIR can generate additional report formats (e.g., DOC, ODT, XLSX) and
+different variants of reports in addition to the
 default ecd file. Following additional reports and report formats can be generated:

 * Metrics in spreadsheet format.
@ -125,7 +141,7 @@ default ecd file. Following additional reports and report formats can be generat

 * Detailed report in ODT format.

-Related cmake options:
+Related CMake options:

 * ``ECLAIR_METRICS_TAB``
 * ``ECLAIR_REPORTS_TAB``
@ -141,13 +157,13 @@ Detail level of full reports
 ============================

 The detail level of the txt and doc full reports can also be adapted by a configuration.
-In this case the following configurations are avilable:
+In this case, the following configurations are available:

 * Show all areas

 * Show only the first area

-Related cmake options:
+Related CMake options:

 * ``ECLAIR_FULL_DOC_ALL_AREAS``
 * ``ECLAIR_FULL_DOC_FIRST_AREA``