includes.rst (2268B)
1 Includes 2 ======== 3 4 This linter checks for unused mfbt headers across the code base. 5 It is preprocessor-agnostic and mostly language-agnostic. 6 It should have no false positive, and allows for false negative. 7 8 Principle 9 --------- 10 11 This linter has two parts: 12 13 First part works by looking for mfbt headers included in any C, Objective-C or 14 C++ file. For each of this header, it consults an abstract API description file 15 and checks if any symbol (be it macro, function, global variable, type 16 definition, operator) described in the API is actually used in the source. If 17 not it reports the error. 18 19 Second part works in a similar manner but for standard C++ headers. 20 21 In both cases, the lookup for symbol is textual, which makes it very fast (no 22 build required), preprocessor-agnostic (all configuration are honored, no header 23 generation required), at the expense of including comments etc. 24 25 API Description 26 --------------- 27 28 The MFBT description file is manually maintained in :searchfox:`MFBT API Description (YAML) 29 <mfbt/api.yml>`. The C++ standard headers are described in 30 :searchfox:`C++ STL Description (Py) <tools/lint/includes/std.py>`. 31 32 It is basically a mapping from header name to a set of symbols, classified by 33 type (macro, function etc). 34 35 The symbols are named independently of their namespace or argument type. 36 Any symbol that is not be used by third-party (e.g. from the ``detail`` 37 namespace, or some auxiliary macro) should not be listed. 38 39 Some checks are done to avoid it from getting out-of-sync, they are performed 40 through:: 41 42 .. parsed-literal:: 43 44 $ mach test tools/lint/test/test_includes.py 45 46 Some of the changes that would make ``api.yml`` get out-of-sync (e.g., renaming 47 a header or removing a symbol) are detected by this test and will break CI. 48 49 Run Locally 50 ----------- 51 52 The mozlint integration of this linter can be run using ``mach``: 53 54 .. parsed-literal:: 55 56 $ mach lint --linter includes <file paths> 57 58 59 Autofix 60 ------- 61 62 The ``includes`` linter provides a ``--fix`` option. 63 64 65 Sources 66 ------- 67 68 * :searchfox:`Linter Configuration (YAML) <tools/lint/includes.yml>` 69 * :searchfox:`MFBT API Description (YAML) <mfbt/api.yml>` 70 * :searchfox:`C++ STL Description (Py) <tools/lint/includes/std.py>` 71 * :searchfox:`Source <tools/lint/includes/__init__.py>`