042e060af6
The existing Clang static analyzer docs mention Clang flags to use, but it wasn't immediately clear to me how to actually use those to analyze Chromium code. This CL adds a paragraph talking about how to execute the analyzer checks using clang-tidy. Bug: None Change-Id: Icef2072f5dd55db96adbbdf72d12329fbde1e767 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3417921 Reviewed-by: Nico Weber <thakis@chromium.org> Commit-Queue: Andrew Williams <awillia@chromium.org> Cr-Commit-Position: refs/heads/main@{#964010}
78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
# The Clang Static Analyzer
|
|
|
|
The Clang C/C++ compiler comes with a static analyzer which can be used to find
|
|
bugs using path sensitive analysis. Path sensitive analysis is
|
|
a technique that explores all the possible branches in code and
|
|
records the codepaths that might lead to bad or undefined behavior,
|
|
like an uninitialized reads, use after frees, pointer leaks, and so on.
|
|
|
|
See the [official Clang static analyzer page](http://clang-analyzer.llvm.org/)
|
|
for more background information.
|
|
|
|
We used to have a bot that continuously ran with the static analyzer,
|
|
but people used to not look at it much.
|
|
|
|
The static analyzer can still be invoked with [clang-tidy](clang_tidy.md).
|
|
|
|
## Recommended checks
|
|
Clang's static analyzer comes with a wide variety of checkers. Some of the
|
|
checks aren't useful because they are intended for different languages,
|
|
platforms, or coding conventions than the ones used for Chromium development.
|
|
|
|
Checkers we found useful were:
|
|
|
|
-analyzer-checker=core
|
|
-analyzer-checker=cpp
|
|
-analyzer-checker=unix
|
|
-analyzer-checker=deadcode
|
|
|
|
As of this writing, the checker suites we support are
|
|
[core](https://clang-analyzer.llvm.org/available_checks.html#core_checkers),
|
|
[cplusplus](https://clang-analyzer.llvm.org/available_checks.html#cplusplus_checkers), and
|
|
[deadcode](https://clang-analyzer.llvm.org/available_checks.html#deadcode_checkers).
|
|
|
|
To easily run these checks against Chromium code via clang-tidy, follow
|
|
[these](clang_tidy.md#evaluating_running-clang_tidy-across-chromium)
|
|
instructions to pull down `tricium_clang_tidy.py` and then pass the following
|
|
argument when invoking the script (`-*` disables all checks and then the
|
|
remaining check name globs enable each category of checks):
|
|
```
|
|
--tidy_checks="-*,clang-analyzer-core*,clang-analyzer-cplusplus*,clang-analyzer-unix*,clang-analyzer-deadcode*"
|
|
```
|
|
A full list of Clang analyzer checks can be found in the
|
|
[Clang-Tidy Checks List](https://clang.llvm.org/extra/clang-tidy/checks/list.html).
|
|
|
|
## Addressing false positives
|
|
|
|
Some of the errors you encounter will be false positives, which occurs when the
|
|
static analyzer naively follows codepaths which are practically impossible to
|
|
hit at runtime. Fortunately, we have a tool at our disposal for guiding the
|
|
analyzer away from impossible codepaths: assertion handlers like
|
|
DCHECK/CHECK/LOG(FATAL). The analyzer won't check the codepaths which we
|
|
assert are unreachable.
|
|
|
|
An example would be that if the analyzer detected the function argument
|
|
`*my_ptr` might be null and dereferencing it would potentially segfault, you
|
|
would see the error `warning: Dereference of null pointer (loaded from variable
|
|
'my_ptr')`. If you know for a fact that my_ptr will not be null in practice,
|
|
then you can place an assert at the top of the function: `DCHECK(my_ptr)`. The
|
|
analyzer will no longer generate the warning.
|
|
|
|
Be mindful about only specifying assertions which are factually correct! Don't
|
|
DCHECK recklessly just to quiet down the analyzer. :)
|
|
|
|
Other types of false positives and their suppressions:
|
|
* Unreachable code paths. To suppress, add the `ANALYZER_SKIP_THIS_PATH();`
|
|
directive to the relevant code block.
|
|
* Dead stores. To suppress, use `[[maybe_unused]]`. This also suppresses dead
|
|
store warnings on conventional builds without static analysis enabled!
|
|
|
|
See the definitions of the `ANALYZER_*` macros in base/logging.h for more
|
|
detailed information about how the annotations are implemented.
|
|
|
|
## Logging bugs
|
|
|
|
If you find any issues with the static analyzer, or find Chromium code behaving
|
|
badly with the analyzer, please check the `Infra>CodeAnalysis` CrBug component
|
|
to look for known issues, or file a bug if it is a new problem.
|