doc: update ECLAIR documentation

LucaCiucci · nashif · commit d8b86f1ac72e · 2025-06-10T12:53:59.000-04:00
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 &lt;luca.ciucci@bugseng.com&gt;
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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
diff --git 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,37 +44,39 @@ 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:
 
 .. code-block:: shell
 
     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``
