1.. _eclair:
2
3ECLAIR support
4##############
5
6Bugseng `ECLAIR <https://www.bugseng.com/eclair/>`__ is a certified
7static analysis tool and platform for software verification.
8Applications range from coding rule validation, with a
9particular emphasis on the MISRA and BARR-C coding standards, to the
10computation of software metrics, to the checking of independence and
11freedom from interference among software components, to the automatic
12detection of important classes of software errors.
13
14.. important::
15
16   ECLAIR is a commercial tool, and it is not free software.
17   You need to have a valid license to use it.
18
19Running ECLAIR
20**************
21
22To run ECLAIR, :ref:`west build <west-building>` should be
23called with a ``-DZEPHYR_SCA_VARIANT=eclair`` parameter.
24
25.. code-block:: shell
26
27    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair
28
29.. note::
30   This will only invoke the ECLAIR analysis with the predefined ruleset ``first_analysis``. If you
31   want to use a different ruleset, you need to provide a configuration file. See the next section
32   for more information.
33
34Configurations
35**************
36
37The configure of the ECLAIR SCA environment can either be done via a cmake options file or with
38adapted options as command line arguments.
39
40To invoke a cmake options file into the ECLAIR call, you can define the ``ECLAIR_OPTIONS_FILE``
41variable, for example:
42
43.. code-block:: shell
44
45    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_OPTIONS_FILE=my_options.cmake
46
47The default (if no config file is given) configuration is always ``first_analysis``,
48which is a tiny selection of rules to verify that everything is correctly working.
49
50If the default configuration wants to be overwritten via the command line and not via a options
51file, that can be achived by giving the argument ``-DOption=ON|OFF``.
52
53For example:
54
55.. code-block:: shell
56
57    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_REPORTS_SARIF=ON
58
59Zephyr is a large and complex project, so the configuration sets are split the
60Zephyr's guidelines selection
61(taken from https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html)
62in five sets to make it more digestible to use on a private machine:
63
64* first_analysis (default): a tiny selection of the projects coding guidelines to verify that
65  everything is correctly working.
66
67* STU: Selection of the projects coding guidelines, which can be verified by analysing the single
68  translation units independently.
69
70* STU_heavy: Selection of complex STU project coding guidelines that require a significant amount
71  of time.
72
73* WP: All whole program project coding guidelines ("system" in MISRA's parlance).
74
75* std_lib: Project coding guidelines about the C Standard Library.
76
77Related cmake options:
78
79* ``ECLAIR_RULESET_FIRST_ANALYSIS``
80* ``ECLAIR_RULESET_STU``
81* ``ECLAIR_RULESET_STU_HEAVY``
82* ``ECLAIR_RULESET_WP``
83* ``ECLAIR_RULESET_STD_LIB``
84
85User defined ruleset
86====================
87
88If you want to use your own defined ruleset instead of the predefined zephyr coding guidelines
89rulesets. You can do so by setting :code:`ECLAIR_RULESET_USER=ON`.
90Created your own rulset file for ECLAIR with the following naming format:
91``analysis_<RULESET>.ecl``. After creating the file define the name of the ruleset for ECLAIR
92with the cmake variable :code:`ECLAIR_USER_RULESET_NAME`.
93If the ruleset file is not in the application source directory, you can define the path to the
94ruleset file with the cmake variable :code:`ECLAIR_USER_RULESET_PATH`. This configuration takes
95relative paths and absolute paths.
96
97Related cmake options and variables:
98
99* ``ECLAIR_RULESET_USER``
100* ``ECLAIR_USER_RULESET_NAME``
101* ``ECLAIR_USER_RULESET_PATH``
102
103Generate additional report formats
104**********************************
105
106ECLAIR can generate additional report formats (e.g. DOC, ODT, XLSX) and
107different variants of repots in addition to the
108default ecd file. Following additional reports and report formats can be generated:
109
110* Metrics in spreadsheet format.
111
112* Findings in spreadsheet format.
113
114* Findings in SARIF format.
115
116* Summary report in plain textual format.
117
118* Summary report in DOC format.
119
120* Summary report in ODT format.
121
122* Detailed reports in txt format.
123
124* Detailed report in DOC format.
125
126* Detailed report in ODT format.
127
128Related cmake options:
129
130* ``ECLAIR_METRICS_TAB``
131* ``ECLAIR_REPORTS_TAB``
132* ``ECLAIR_REPORTS_SARIF``
133* ``ECLAIR_SUMMARY_TXT``
134* ``ECLAIR_SUMMARY_DOC``
135* ``ECLAIR_SUMMARY_ODT``
136* ``ECLAIR_FULL_TXT``
137* ``ECLAIR_FULL_DOC``
138* ``ECLAIR_FULL_ODT``
139
140Detail level of full reports
141============================
142
143The detail level of the txt and doc full reports can also be adapted by a configuration.
144In this case the following configurations are avilable:
145
146* Show all areas
147
148* Show only the first area
149
150Related cmake options:
151
152* ``ECLAIR_FULL_DOC_ALL_AREAS``
153* ``ECLAIR_FULL_DOC_FIRST_AREA``
154* ``ECLAIR_FULL_TXT_ALL_AREAS``
155* ``ECLAIR_FULL_TXT_FIRST_AREA``
156