Skip to content

Commit

Permalink
add checker and analyzer configuration documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Gyorgy Orban committed Aug 9, 2018
1 parent a4551d9 commit 9bb27be
Show file tree
Hide file tree
Showing 3 changed files with 131 additions and 0 deletions.
122 changes: 122 additions & 0 deletions docs/checker_and_analyzer_configuration.md
View file
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 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
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
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

0 comments on commit 9bb27be

Please sign in to comment.