Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add checker and analyzer configuration documentation #1703

Merged
merged 1 commit into from
Aug 27, 2018
Merged

add checker and analyzer configuration documentation #1703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions docs/checker_and_analyzer_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Configure Clang Static Analyzer and checkers

Checker configuration can be done through the `--saargs` analysis option which forwards arguments without modification to the Clang Static Analyzer:
```
CodeChecker analyze --saargs static_analyzer.cfg
```

In the `static_analyzer.cfg` file various static analyzer and checker related configuration options can be configured like this:
```
-Xclang -analyzer-config -Xclang unix.Malloc:Optimistic=true -Xclang -analyzer-max-loop -Xclang 20
```
__Before every configuration option '-Xclang' argument should be written and all the configuration options sould be in one line!__

In the `static_analyzer.cfg` example file we set a checker specific configuration option `unix.Malloc:Optimistic=true` for the `unix.Malloc` checker and a static analyzer configuration option `analyzer-max-loop` (the maximum number of times the analyzer will go through a loop, the default value is 4).

## Checker specific configuration options
This is not a comprehensive list view checker [documentation or implementation](https://github.com/llvm-mirror/clang/tree/master/lib/StaticAnalyzer/Checkers) for available configuration options:

| checker name | configuration option | default value | available values | description |
|--------------|--------------------------------|---------------|------------------|----------------------------------------------------------------------------------------|
| nullability | NoDiagnoseCallsToSystemHeaders | false | true/false | If true, the checker will not diagnose nullability issues for calls to system headers. |
| unix.Malloc | Optimistic | false | true/false | |


## Clang Static Analyzer configuration options
This is not a comprehesive list, check out the [clang static analyzer documentation](https://github.com/llvm-mirror/clang/tree/master/docs) or source code for more details about the configuration options.

| configuration option | default value | available values | description |
|---------------------------------------|-------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------|
| analyzer-max-loop | 4 | | |
| inline-lambdas | true | | |
| ipa | dynamic-bifurcate | | [inter procedural analysis](https://github.com/llvm-mirror/clang/blob/master/docs/analyzer/IPA.txt) |
| ipa-always-inline-size | 3 | | |
| mode | deep | deep, shallow | |
| max-inlinable-size | 100 | | 100 for deep mode, 4 for shallow |
| max-nodes | 225000 | | 22500 for deep, 75000 for shallow, maximum number of nodes for top level functions |
| unroll-loops | false | true/false | |
| widen-loops | false | true/false | |
| suppress-null-return-paths | false | | |
| c++-inlining | constructors | constructors, destructors, none, methods | [inlining options](https://github.com/llvm-mirror/clang/blob/master/docs/analyzer/IPA.txt) |
| leak-diagnostics-reference-allocation | false | true/false | |
| max-times-inline-large | 32 | | |
| region-store-small-struct-limit | 2 | | |
| path-diagnostics-alternate | false | true/false | |
| report-in-main-source-file | true | true/false | |
| min-cfg-size-treat-functions-as-large | 14 | | |
| cfg-conditional-static-initializers | true | | |
| cfg-implicit-dtors | true | true/false | |
| cfg-lifetime | false | true/false | |
| cfg-loopexit | false | true/false | |
| cfg-temporary-dtors | false | true/false | |
| faux-bodies | true | true/false | |
| graph-trim-interval | 1000 | | |


# Configure Clang tidy checkers

## Using Clang tidy configuration files

__clang-tidy__ attempts to read configuration for each analyzed source file from a `.clang-tidy` file located in the closest parent directory of the analyzed source file.

The `.clang-tidy` configuration file can be in JSON or YAML format.

JSON:
```json
{
"Checks": "clang-diagnostic-*,clang-analyzer-*",
"WarningsAsErrors": "",
"HeaderFilterRegex": "",
"AnalyzeTemporaryDtors": false,
"CheckOptions": [
{
"key": "google-readability-braces-around-statements.ShortStatementLines",
"value": "1"
},
{
"key": "modernize-loop-convert.MaxCopySize",
"value": "16"
},
{
"key": "modernize-loop-convert.NamingStyle",
"value": "CamelCase"
},
{
"key": "modernize-use-nullptr.NullMacros",
"value": "NULL"
}
]
}
```

or the same configuration in YAML format:

```yaml
---
Checks: 'clang-diagnostic-*,clang-analyzer-*'
WarningsAsErrors: ''
HeaderFilterRegex: ''
AnalyzeTemporaryDtors: false
CheckOptions:
- key: google-readability-braces-around-statements.ShortStatementLines
value: '1'
- key: modernize-loop-convert.MaxCopySize
value: '16'
- key: modernize-loop-convert.NamingStyle
value: CamelCase
- key: modernize-use-nullptr.NullMacros
value: 'NULL'
...
```

## Using tidyargs option in CodeChecker

The `--tidyargs` analysis argument can be used to forward configuration options through CodeChecker to the clang-tidy analyzer.
```
CodeChecker analyze --tidyargs tidy_analyzer.cfg
```
Where the ```tidy_analyzer.cfg``` config file content looks like this where the configuration arguments (json in this case) should be in one line :

```
-config="{ "Checks": "clang-diagnostic-*,clang-analyzer-*", "WarningsAsErrors": "", "HeaderFilterRegex": "", "AnalyzeTemporaryDtors": false, "CheckOptions": [ { "key": "google-readability-braces-around-statements.ShortStatementLines", "value": "1" }, { "key": "modernize-loop-convert.MaxCopySize", "value": "16" }, { "key": "modernize-loop-convert.NamingStyle", "value": "CamelCase" }, { "key": "modernize-use-nullptr.NullMacros", "value": "NULL" } ] }"
```
5 changes: 5 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Table of Contents
* [Step 5: Fine tune Analysis configuration](#step-5)
* [Ignore modules from your analysis](#ignore-modules)
* [Enable/Disable Checkers](#enable-disable-checkers)
* [Configure Checkers](#configure-checkers)
* [Identify files that failed analysis](#identify-files)
* [Step 6: Integrate CodeChecker into your CI loop](#step-6)
* [Storing & Updating runs](#storing-runs)
Expand Down Expand Up @@ -241,6 +242,10 @@ For example to enable alpha checkers additionally to the defaults
CodeChecker analyze -e alpha -b "make" -i ./skip.file" -o ./reports
```

### <a name="configure-checkers"></a> Configure Checkers

See [Configure Clang Static Analyzer and checkers](/docs/checker_and_analyzer_configuration.md) documentation for a detailed description.

### <a name="identify-files"></a> Identify files that failed analysis
After execution of
```
Expand Down
4 changes: 4 additions & 0 deletions docs/user_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -536,6 +536,10 @@ used to specify which analyzer tool should be used (by default, all supported
are used). The tools are completely independent, so either can be omitted if
not present as they are provided by different binaries.

See [Configure Clang Static Analyzer and checkers](/docs/checker_and_analyzer_configuration.md) documentation for
a more detailed description how to use the `saargs` and `tidyargs` arguments.


#### <a name="include-path"></a> Compiler-specific include path and define detection (cross compilation)

Some of the include paths are hardcoded during compiler build. If a (cross)
Expand Down