michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update ECLAIR documentation

Browse source 
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>
This commit is contained in:
Luca Ciucci 2025-05-02 10:19:57 +02:00 • committed by Anas Nashif
commit d8b86f1ac7
7 changed files with 51 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

2
cmake/sca/eclair/ECL/analysis_STU.ecl
View file

@ -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

2
cmake/sca/eclair/ECL/analysis_WP.ecl
View file

@ -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

2
cmake/sca/eclair/ECL/analysis_first_analysis.ecl
View file

@ -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

2
cmake/sca/eclair/ECL/analysis_heavy_STU.ecl
View file

@ -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

2
cmake/sca/eclair/ECL/analysis_std_lib.ecl
View file

@ -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

2
cmake/sca/eclair/ECL/analysis_zephyr_guidelines.ecl
View file

@ -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

74
doc/develop/sca/eclair.rst
View file

@ -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``