69 lines
2.2 KiB
Markdown
69 lines
2.2 KiB
Markdown
# Includes
|
|
|
|
This linter checks for unused mfbt headers across the code base.
|
|
It is preprocessor-agnostic and mostly language-agnostic.
|
|
It should have no false positive, and allows for false negative.
|
|
|
|
## Principle
|
|
|
|
This linter has two parts:
|
|
|
|
First part works by looking for mfbt headers included in any C, Objective-C or
|
|
C++ file. For each of this header, it consults an abstract API description file
|
|
and checks if any symbol (be it macro, function, global variable, type
|
|
definition, operator) described in the API is actually used in the source. If
|
|
not it reports the error.
|
|
|
|
Second part works in a similar manner but for standard C++ headers.
|
|
|
|
In both cases, the lookup for symbol is textual, which makes it very fast (no
|
|
build required), preprocessor-agnostic (all configuration are honored, no header
|
|
generation required), at the expense of including comments etc.
|
|
|
|
## API Description
|
|
|
|
The MFBT description file is manually maintained in {searchfox}`MFBT API Description (YAML)
|
|
<mfbt/api.yml>`. The C++ standard headers are described in
|
|
{searchfox}`C++ STL Description (Py) <tools/lint/includes/std.py>`.
|
|
|
|
It is basically a mapping from header name to a set of symbols, classified by
|
|
type (macro, function etc).
|
|
|
|
The symbols are named independently of their namespace or argument type.
|
|
Any symbol that is not be used by third-party (e.g. from the `detail`
|
|
namespace, or some auxiliary macro) should not be listed.
|
|
|
|
Some checks are done to avoid it from getting out-of-sync, they are performed
|
|
through:
|
|
|
|
```
|
|
.. parsed-literal::
|
|
```
|
|
|
|
\$ mach test tools/lint/test/test_includes.py
|
|
|
|
Some of the changes that would make `api.yml` get out-of-sync (e.g., renaming
|
|
a header or removing a symbol) are detected by this test and will break CI.
|
|
|
|
## Run Locally
|
|
|
|
The mozlint integration of this linter can be run using `mach`:
|
|
|
|
```{eval-rst}
|
|
.. parsed-literal::
|
|
|
|
$ mach lint --linter includes <file paths>
|
|
|
|
```
|
|
|
|
## Autofix
|
|
|
|
The `includes` linter provides a `--fix` option.
|
|
|
|
## Sources
|
|
|
|
- {searchfox}`Linter Configuration (YAML) <tools/lint/includes.yml>`
|
|
- {searchfox}`MFBT API Description (YAML) <mfbt/api.yml>`
|
|
- {searchfox}`C++ STL Description (Py) <tools/lint/includes/std.py>`
|
|
- {searchfox}`Source <tools/lint/includes/__init__.py>`
|