existing.rst (9594B)
1 Existing Infrastructure and Analysis 2 ==================================== 3 4 This document is about how Static Analysis occurs at Mozilla: the Firefox-specific and general llvm clang-tidy checks that are run on submissions in Phabricator and how to run them locally. For information about how to develop your own static analysis checks, please see `Writing New Firefox-Specific Checks <../static-analysis/writing-new/index.html>`_. 5 6 For linting, please see the `linting documentation <../lint/index.html>`_. 7 8 For reviews, use the `#static-analysis-reviewers review group <https://phabricator.services.mozilla.com/project/view/120/>`__. 9 Ask questions on `#static-analysis:mozilla.org <https://chat.mozilla.org/#/room/#static-analysis:mozilla.org>`__. 10 11 12 Clang-Tidy static analysis 13 -------------------------- 14 15 As explained earlier, our current static-analysis infrastructure is based on 16 `clang-tidy <http://clang.llvm.org/extra/clang-tidy/>`__. The checkers that 17 we use are split into 3 categories: 18 19 #. :searchfox:`Firefox specific checkers <build/clang-plugin>`. They detect incorrect Gecko programming 20 patterns which could lead to bugs or security issues. 21 #. `Clang-tidy checkers <https://clang.llvm.org/extra/clang-tidy/checks/list.html>`_. They aim to suggest better programming practices 22 and to improve memory efficiency and performance. 23 #. `Clang-analyzer checkers <https://clang-analyzer.llvm.org/>`_. These checks are more advanced, for example 24 some of them can detect dead code or memory leaks, but as a typical 25 side effect they have false positives. Because of that, we have 26 disabled them for now, but will enable some of them in the near 27 future. 28 29 In order to simplify the process of static-analysis we have focused on 30 integrating this process with Phabricator and mach. A list of some 31 checkers that are used during automated scan can be found 32 :searchfox:`here <tools/clang-tidy/config.yaml>`. 33 34 Static analysis at review phase 35 ------------------------------- 36 37 We created a TaskCluster bot that runs clang static analysis on every 38 patch submitted to Phabricator. It then quickly reports any code defects 39 directly on the review platform, thus preventing bad patches from 40 landing until all their defects are fixed. Currently, its feedback is 41 posted in about 10 minutes after a patch series is published on the 42 review platform. 43 44 As part of the process, the various linting jobs are also executed 45 using try. This can be also used to add new jobs, see: :ref:`attach-job-review`. 46 An example of automated review can be found `on 47 phabricator <https://phabricator.services.mozilla.com/D2066>`__. 48 49 50 ./mach static-analysis 51 ---------------------- 52 53 The ``./mach static-analysis`` command is supported on all Firefox built platforms. During the first run it 54 automatically installs all of its dependencies, such as the clang-tidy 55 executable, in the .mozbuild folder thus making it very easy to use. The 56 resources that are used are provided by toolchain artifacts clang-tidy 57 target. 58 59 This is used through ``mach static-analysis`` command that has the 60 following parameters: 61 62 - ``check`` - Runs the checks using the installed helper tool from 63 ~/.mozbuild. 64 - ``--checks, -c`` - Checks to enabled during the scan. The checks 65 enabled 66 :searchfox:`in the yaml file <tools/clang-tidy/config.yaml>` 67 are used by default. 68 - ``--fix, -f`` - Try to autofix errors detected by the checkers. 69 Depending on the checker, this option might not do anything. 70 The list of checkers with autofix can be found on the `clang-tidy website <https://clang.llvm.org/extra/clang-tidy/checks/list.html>`__. 71 - ``--header-filter, -h-f`` - Regular expression matching the names of 72 the headers to output diagnostic from. Diagnostic from the main file 73 of each translation unit are always displayed. 74 75 As an example we run static-analysis through mach on 76 ``dom/presentation/Presentation.cpp`` with 77 ``google-readability-braces-around-statements`` check and autofix we 78 would have: 79 80 .. code-block:: shell 81 82 ./mach static-analysis check --checks="-*, google-readability-braces-around-statements" --fix dom/presentation/Presentation.cpp 83 84 If you want to use a custom clang-tidy binary this can be done by using 85 the ``install`` subcommand of ``mach static-analysis``, but please note 86 that the archive that is going to be used must be compatible with the 87 directory structure clang-tidy from toolchain artifacts. 88 89 .. code-block:: shell 90 91 ./mach static-analysis install clang.tar.gz 92 93 94 Regression Testing 95 ------------------ 96 97 In order to prevent regressions in our clang-tidy based static analysis, 98 we have created a 99 :searchfox:`task <taskcluster/kinds/static-analysis-autotest/kind.yml>` 100 on automation. This task runs on each commit and launches a test suite 101 that is integrated into mach. 102 103 The test suite implements the following: 104 105 - Downloads the necessary clang-tidy artifacts. 106 - Reads the 107 :searchfox:`configuration <tools/clang-tidy/config.yaml>` 108 file. 109 - For each checker reads the test file plus the expected result. A 110 sample of test and expected result can be found 111 :searchfox:`in the test file <tools/clang-tidy/test/clang-analyzer-deadcode.DeadStores.cpp>` 112 and 113 :searchfox:`the json file <tools/clang-tidy/test/clang-analyzer-deadcode.DeadStores.json>`. 114 115 This testing suit can be run locally by doing the following: 116 117 .. code-block:: shell 118 119 ./mach static-analysis autotest 120 121 If we want to test only a specific checker, let's say 122 modernize-raw-string-literal, we can run: 123 124 .. code-block:: shell 125 126 ./mach static-analysis autotest modernize-raw-string-literal 127 128 If we want to add a new checker we need to generate the expected result 129 file, by doing: 130 131 .. code-block:: shell 132 133 ./mach static-analysis autotest modernize-raw-string-literal -d 134 135 136 Build-time static-analysis 137 -------------------------- 138 139 If you want to build with the Firefox Clang plug-in 140 (located in ``/build/clang-plugin`` and associated with 141 ``MOZ_CLANG_PLUGIN`` and the attributes in ``/mfbt/Attributes.h``) 142 just add ``--enable-clang-plugin`` to your mozconfig! 143 If you want to also have our experimental checkers that will produce ``warnings`` as 144 diagnostic messages also add ``--enable-clang-plugin-alpha``. 145 This requires to build Firefox using Clang. 146 147 Configuring the build environment 148 --------------------------------- 149 150 Once you have your Clang build in place, you will need to set up tools 151 to use it. 152 A full working .mozconfig for the desktop browser is: 153 154 .. code-block:: shell 155 156 . $topsrcdir/browser/config/mozconfig 157 mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/obj-ff-dbg 158 159 ac_add_options --enable-debug 160 161 Attempts to use ``ccache`` will likely result in failure to compile. It 162 is also necessary to avoid optimized builds, as these will modify macros 163 which will result in many false positives. 164 165 At this point, your Firefox build environment should be configured to 166 compile via the Clang static analyzer! 167 168 169 Performing scanning builds 170 -------------------------- 171 172 It is not enough to simply start the build like normal. Instead, you 173 need to run the build through a Clang utility script which will keep 174 track of all produced analysis and consolidate it automatically. 175 176 Reports are published daily on 177 `https://sylvestre.ledru.info/reports/fx-scan-build/ <http://sylvestre.ledru.info/reports/fx-scan-build/>`__ 178 Many of the defects reported as sources for Good First Bug. 179 180 That script is scan-build. You can find it in 181 ``$clang_source/tools/scan-build/scan-build``. 182 183 Try running your build through ``scan-build``: 184 185 .. code-block:: shell 186 187 $ cd /path/to/mozilla/source 188 189 # Blow away your object directory because incremental builds don't make sense 190 $ rm -rf obj-dir 191 192 # To start the build: 193 scan-build --show-description ./mach build -v 194 195 # The above should execute without any errors. However, it should take longer than 196 # normal because all compilation will be executing through Clang's static analyzer, 197 # which adds overhead. 198 199 If things are working properly, you should see a bunch of console spew, 200 just like any build. 201 202 The first time you run scan-build, CTRL+C after a few files are 203 compiled. You should see output like: 204 205 .. code-block:: shell 206 207 scan-build: 3 bugs found. 208 scan-build: Run 'scan-view /Users/gps/tmp/mcsb/2011-12-15-3' to examine bug reports. 209 210 If you see a message like: 211 212 .. code-block:: shell 213 214 scan-build: Removing directory '/var/folders/s2/zc78dpsx2rz6cpc_21r9g5hr0000gn/T/scan-build-2011-12-15-1' because it contains no reports. 215 216 Either no static analysis results were available yet or your environment 217 is not configured properly. 218 219 By default, ``scan-build`` writes results to a folder in a 220 pseudo-temporary location. You can control where results go by passing 221 the ``-o /path/to/output`` arguments to ``scan-build``. 222 223 You may also want to run ``scan-build --help`` to see all the options 224 available. For example, it is possible to selectively enable and disable 225 individual analyzers. 226 227 228 Analyzing the output 229 -------------------- 230 231 Once the build has completed, ``scan-build`` will produce a report 232 summarizing all the findings. This is called ``index.html`` in the 233 output directory. You can run ``scan-view`` (from 234 ``$clang_source/tools/scan-view/scan-view``) as ``scan-build's`` output 235 suggests; this merely fires up a local HTTP server. Or you should be 236 able to open the ``index.html`` directly with your browser. 237 238 239 False positives 240 --------------- 241 242 By definition, there are currently false positives in the static 243 analyzer. A lot of these are due to the analyzer having difficulties 244 following the relatively complicated error handling in various 245 preprocessor macros.