Skip to content

Commit ce5ed25

Browse files
dkruppdkrupp
authored
Report directory and metadata.json format specification (#4797)
* Report directory and metadata.json format specification * fixit description added * Adding links to the main readme * fixing a link
1 parent 5ce99e3 commit ce5ed25

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -411,9 +411,12 @@ you should be greeted with a web application showing you the analysis results.
411411

412412
## Developer documentations
413413
* [Architecture](architecture.md)
414+
* [Report Directory Specification](report_directory.md)
415+
* [Plist Report Format Specification](tools/plist.md)
414416
* [Package layout](package_layout.md)
415417
* [Dependencies](deps.md)
416418
* [Thrift interface](web/api/README.md)
419+
* [Sample CodeChecker Command Line Client](/scripts/thrift/README.md)
417420
* [Package and integration tests](tests.md)
418421
* [Server-side background tasks](web/background_tasks.md)
419422

‎docs/report_directory.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# CodeChecker Report Directory Structure
2+
3+
## Overview
4+
5+
This directory contains static analysis reports generated by `CodeChecker analyze` for C/C++ projects. The report directory format is standardized within CodeChecker and it is assumed by various sub-commands such as `CodeChecker parse/store`.
6+
7+
Other tools, such as CodeChecker [bazel rules](https://github.com/Ericsson/rules_codechecker) should follow this specification to be compatible with the CodeChecker ecosystem.
8+
9+
## Directory Layout
10+
11+
```
12+
report_directory/
13+
├── metadata.json # Analysis metadata and configuration. (used opionally by store)
14+
├── compiler_info.json # Compiler details and flags. (for debugging)
15+
├── compile_cmd.json # Compilation commands. (for debugging)
16+
├── unique_compile_commands.json # Deduplicated compilation commands (for debugging)
17+
├── <file>_<analyzer>_<hash>.plist # Successful analysis results (used by parse and store)
18+
├── <file>_<analyzer>_<hash>.plist.err # Analysis error logs (used by parse --status)
19+
├── cppcheck/ # Cppcheck backup files
20+
│ └── <hash>/
21+
│ └── *.plist.bak
22+
├── gcc/ # GCC analyzer backup files (for debugging)
23+
│ └── *.sarif.bak
24+
├── fixit/ # Clang-tidy fix suggestions (used optionall by store))
25+
│ └── *_clang-tidy_*.yaml
26+
├── failed/ # Failed analysis artifacts (for debugging)
27+
│ └── *_compile_error.zip
28+
└── ctu_connections/ # Cross-translation unit data (for debugging)
29+
```
30+
### Usage
31+
32+
* `CodeChecker store` stores the reports found in the `plist` files and optionally parses the information in the `metadata.json`.
33+
34+
* `CodeChecker parse` displays the reports in the `plist` files and displays analysis status based on the existence of the `plist` or `plist.err` files.
35+
36+
* `CodeChecker parse --file` relies on the `result_source_files` section of the `metadata.json`.
37+
38+
* `CodeChecker fixit` relies on the `fixit` subdirectory.
39+
## File Types
40+
41+
### Information files
42+
43+
- **metadata.json** - Contains:
44+
- CodeChecker version
45+
- Analysis command
46+
- Enabled analyzers and checkers
47+
- Source file mappings
48+
- Analysis statistics
49+
50+
- **compiler_info.json** - Compiler configuration:
51+
- Compiler path and version
52+
- Include directories
53+
- Language standard
54+
- Target architecture
55+
56+
- **compile_cmd.json** - Compilation database with build commands for each source file
57+
58+
### Report Files
59+
60+
Format: `<source_file>_<analyzer>_<hash>.plist`
61+
62+
**Analyzers:**
63+
- `clang-tidy` - C++ linter with 600+ checks
64+
- `clangsa` - Clang Static Analyzer
65+
- `cppcheck` - C/C++ static analyzer
66+
- `gcc` - GCC static analyzer
67+
68+
**Report Format:** Apple Property List (plist) XML containing:
69+
- Diagnostics with severity, category, and description
70+
- File locations (line, column)
71+
- Execution paths showing issue flow
72+
- Check names for filtering
73+
74+
**Error Files** (`.plist.err`):
75+
- Generated when analysis fails
76+
- Contains analyzer command, return code, stderr, and stdout
77+
- Includes compiler errors and warnings that prevented analysis
78+
79+
### Auxiliary Directories
80+
81+
- **fixit/** - YAML files with automated fix suggestions from clang-tidy
82+
- **cppcheck/**, **gcc/** - Backup copies of original reports
83+
- **failed/** - ZIP archives of failed analysis attempts with compile errors
84+
- **ctu_connections/** - Cross-translation unit analysis metadata
85+
86+
## Metadata Structure
87+
88+
The `metadata.json` file contains comprehensive information about the analysis run, including configuration, enabled checkers, and statistics.
89+
90+
### Field Descriptions
91+
92+
`Metadata format version : 2`
93+
94+
**Top-level fields:**
95+
- `version` - Metadata format version
96+
- `tools` - Array of tool configurations (typically one CodeChecker entry)
97+
98+
**Tool object fields:**
99+
- `name` - Tool name ("codechecker")
100+
- `action_num` - Number of compilation actions analyzed
101+
- `command` - Full command line used to invoke the analysis
102+
- `version` - CodeChecker version with git commit hash
103+
- `working_directory` - Project root directory where analysis was executed
104+
- `output_path` - Absolute path to report directory
105+
- `result_source_files` - Map of report files to their source files
106+
- `analyzers` - Configuration for each analyzer (clangsa, clang-tidy, cppcheck, gcc)
107+
- `skipped` - Number of skipped source files
108+
- `timestamps` - Analysis start (`begin`) and end (`end`) times in Unix epoch
109+
110+
**Analyzer object fields:**
111+
- `checkers` - Map of checker names to enabled status (true/false)
112+
- `analyzer_statistics` - Analysis results summary
113+
- `failed` - Count of failed analyses
114+
- `failed_sources` - List of source files that failed analysis
115+
- `successful` - Count of successful analyses
116+
- `successful_sources` - List of successfully analyzed source files
117+
- `version` - Analyzer version
118+
119+
### Example
120+
121+
```json
122+
{
123+
"version": 2,
124+
"tools": [{
125+
"name": "codechecker",
126+
"action_num": 3,
127+
"command": [
128+
"analyze",
129+
"-d", "default",
130+
"-e", "optin.taint",
131+
"--timeout", "300",
132+
"./src/file.c",
133+
"-o", "./reports"
134+
],
135+
"version": "6.28 (2281ca3ce898b1061063ded46b7754f5da6281f5)",
136+
"working_directory": "/workspace/project",
137+
"output_path": "/workspace/project/reports",
138+
"result_source_files": {
139+
"/workspace/project/reports/file.c_clangsa_abc123.plist": "/workspace/project/src/file.c"
140+
},
141+
"analyzers": {
142+
"clangsa": {
143+
"checkers": {
144+
"optin.taint.GenericTaint": true,
145+
"optin.taint.TaintedAlloc": true,
146+
"core.NullDereference": false,
147+
"core.DivideZero": false
148+
},
149+
"analyzer_statistics": {
150+
"failed": 0,
151+
"failed_sources": [],
152+
"successful": 3,
153+
"successful_sources": [
154+
"/workspace/project/src/file.c"
155+
],
156+
"version": "20.0.0"
157+
}
158+
}
159+
},
160+
"skipped": 0,
161+
"timestamps": {
162+
"begin": 1770915554.200186,
163+
"end": 1770915561.956268
164+
}
165+
}]
166+
}
167+
```
168+
169+
## Report File Structure
170+
171+
For detailed plist format specification, see [plist.md](tools/plist.md).
172+
173+
### Success Report (.plist)
174+
175+
```xml
176+
<plist>
177+
<dict>
178+
<key>diagnostics</key>
179+
<array>
180+
<dict>
181+
<key>check_name</key>
182+
<string>cert-err33-c</string>
183+
<key>description</key>
184+
<string>Issue description</string>
185+
<key>category</key>
186+
<string>cert</string>
187+
<key>location</key>
188+
<dict>
189+
<key>line</key><integer>564</integer>
190+
<key>col</key><integer>5</integer>
191+
<key>file</key><integer>0</integer>
192+
</dict>
193+
<key>path</key>
194+
<array><!-- Execution path --></array>
195+
</dict>
196+
</array>
197+
<key>files</key>
198+
<array><!-- Source file paths --></array>
199+
</dict>
200+
</plist>
201+
```
202+
203+
### Error Report (.plist.err)
204+
205+
```xml
206+
<plist>
207+
<dict>
208+
<key>analyzer_cmd</key>
209+
<array><!-- Full analyzer command --></array>
210+
<key>analyzer_name</key>
211+
<string>clang-tidy</string>
212+
<key>return_code</key>
213+
<integer>1</integer>
214+
<key>stderr</key>
215+
<string>Error messages</string>
216+
<key>stdout</key>
217+
<string>Warnings and errors</string>
218+
</dict>
219+
</plist>
220+
```

0 commit comments

Comments
 (0)