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
14Prerequisites
15*************
16
17The ECLAIR tool must be installed and made available in the operating system's
18PATH variable.
19
20To verify the installation, you can run:
21
22.. code-block:: shell
23
24   eclair -version
25
26A valid license or trial license is required to use ECLAIR. To request a trial
27license, visit `this page <https://www.bugseng.com/eclair/free-trial>`__.
28
29Running ECLAIR
30**************
31
32To run ECLAIR, :ref:`west build <west-building>` should be
33called with a ``-DZEPHYR_SCA_VARIANT=eclair`` parameter.
34
35.. code-block:: shell
36
37    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair
38
39.. note::
40   This will only invoke the ECLAIR analysis with the predefined ruleset ``first_analysis``. If you
41   want to use a different ruleset, you need to provide a configuration file. See the next section
42   for more information.
43
44Configurations
45**************
46
47The configuration of the ECLAIR SCA environment can either be done via a CMake
48options file or with adapted options as command line arguments.
49
50To invoke a CMake options file into the ECLAIR call, you can define the
51``ECLAIR_OPTIONS_FILE`` variable, for example:
52
53.. code-block:: shell
54
55    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_OPTIONS_FILE=my_options.cmake
56
57The default (if no config file is given) configuration is always
58``first_analysis``, which is a tiny selection of rules to verify that
59everything is correctly working.
60
61If the default configuration wants to be overwritten via the command line and
62not via an options file, that can be achieved by giving the argument
63``-DOption=ON|OFF``.
64
65For example:
66
67.. code-block:: shell
68
69    west build -b mimxrt1064_evk samples/basic/blinky -- -DZEPHYR_SCA_VARIANT=eclair -DECLAIR_REPORTS_SARIF=ON
70
71Zephyr is a large and complex project, so the configuration sets are split into
72the Zephyr's guidelines selection
73(taken from https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html)
74in five sets to make it more digestible to use on a private machine:
75
76* first_analysis (default): a tiny selection of the project's coding guidelines to verify that
77  everything is correctly working.
78
79* STU: Selection of the project's coding guidelines, which can be verified by analyzing the single
80  translation units independently.
81
82* STU_heavy: Selection of complex STU project coding guidelines that require a significant amount
83  of time.
84
85* WP: All whole program project coding guidelines ("system" in MISRA's parlance).
86
87* std_lib: Project coding guidelines about the C Standard Library.
88
89In addition, the zephyr_guidelines ruleset contains all the main rules
90listed in the `Coding Guidelines <https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html>`__.
91
92Related CMake options:
93
94* ``ECLAIR_RULESET_FIRST_ANALYSIS``
95* ``ECLAIR_RULESET_STU``
96* ``ECLAIR_RULESET_STU_HEAVY``
97* ``ECLAIR_RULESET_WP``
98* ``ECLAIR_RULESET_STD_LIB``
99* ``ECLAIR_RULESET_ZEPHYR_GUIDELINES``
100
101User-defined ruleset
102====================
103
104If you want to use your own defined ruleset instead of the predefined Zephyr coding guidelines
105rulesets, you can do so by setting :code:`ECLAIR_RULESET_USER=ON`.
106Create your own ruleset file for ECLAIR with the following naming format:
107``analysis_<RULESET>.ecl``. After creating the file, define the name of the ruleset for ECLAIR
108with the CMake variable :code:`ECLAIR_USER_RULESET_NAME`.
109If the ruleset file is not in the application source directory, you can define the path to the
110ruleset file with the CMake variable :code:`ECLAIR_USER_RULESET_PATH`. This configuration takes
111relative paths and absolute paths.
112
113Related CMake options and variables:
114
115* ``ECLAIR_RULESET_USER``
116* ``ECLAIR_USER_RULESET_NAME``
117* ``ECLAIR_USER_RULESET_PATH``
118
119Generate additional report formats
120**********************************
121
122ECLAIR can generate additional report formats (e.g., DOC, ODT, XLSX) and
123different variants of reports in addition to the
124default ecd file. Following additional reports and report formats can be generated:
125
126* Metrics in spreadsheet format.
127
128* Findings in spreadsheet format.
129
130* Findings in SARIF format.
131
132* Summary report in plain textual format.
133
134* Summary report in DOC format.
135
136* Summary report in ODT format.
137
138* Summary report in HTML format.
139
140* Detailed reports in txt format.
141
142* Detailed report in DOC format.
143
144* Detailed report in ODT format.
145
146* Detailed report in HTML format.
147
148Related CMake options:
149
150* ``ECLAIR_METRICS_TAB``
151* ``ECLAIR_REPORTS_TAB``
152* ``ECLAIR_REPORTS_SARIF``
153* ``ECLAIR_SUMMARY_TXT``
154* ``ECLAIR_SUMMARY_DOC``
155* ``ECLAIR_SUMMARY_ODT``
156* ``ECLAIR_SUMMARY_HTML``
157* ``ECLAIR_FULL_TXT``
158* ``ECLAIR_FULL_DOC``
159* ``ECLAIR_FULL_ODT``
160* ``ECLAIR_FULL_HTML``
161
162Detail level of full reports
163============================
164
165The detail level of the txt and doc full reports can also be adapted by a configuration.
166In this case, the following configurations are available:
167
168* Show all areas
169
170* Show only the first area
171
172Related CMake options:
173
174* ``ECLAIR_FULL_DOC_ALL_AREAS``
175* ``ECLAIR_FULL_DOC_FIRST_AREA``
176* ``ECLAIR_FULL_TXT_ALL_AREAS``
177* ``ECLAIR_FULL_TXT_FIRST_AREA``
178