Skip to content

Commit 8d165d6

Browse files
dkruppdkrupp
committed
Report directory and metadata.json format specification
1 parent 5ce99e3 commit 8d165d6

1 file changed

Lines changed: 233 additions & 0 deletions

File tree

‎docs/report_directory.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
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+
`CodeChecker store` stores the reports found in the `plist` files and optionally parses the information in the `metadata.json`.
31+
32+
`CodeChecker parse` displays the reports in the `plist` files and displays analysis status based on the existence of the `plist` or `plist.err` files.
33+
34+
`CodeChecker parse --file` relies on the `result_source_files` section of the `metadata.json`.
35+
36+
## File Types
37+
38+
### Information files
39+
40+
- **metadata.json** - Contains:
41+
- CodeChecker version
42+
- Analysis command
43+
- Enabled analyzers and checkers
44+
- Source file mappings
45+
- Analysis statistics
46+
47+
- **compiler_info.json** - Compiler configuration:
48+
- Compiler path and version
49+
- Include directories
50+
- Language standard
51+
- Target architecture
52+
53+
- **compile_cmd.json** - Compilation database with build commands for each source file
54+
55+
### Report Files
56+
57+
Format: `<source_file>_<analyzer>_<hash>.plist`
58+
59+
**Analyzers:**
60+
- `clang-tidy` - C++ linter with 600+ checks
61+
- `clangsa` - Clang Static Analyzer
62+
- `cppcheck` - C/C++ static analyzer
63+
- `gcc` - GCC static analyzer
64+
65+
**Report Format:** Apple Property List (plist) XML containing:
66+
- Diagnostics with severity, category, and description
67+
- File locations (line, column)
68+
- Execution paths showing issue flow
69+
- Check names for filtering
70+
71+
**Error Files** (`.plist.err`):
72+
- Generated when analysis fails
73+
- Contains analyzer command, return code, stderr, and stdout
74+
- Includes compiler errors and warnings that prevented analysis
75+
76+
### Auxiliary Directories
77+
78+
- **fixit/** - YAML files with automated fix suggestions from clang-tidy
79+
- **cppcheck/**, **gcc/** - Backup copies of original reports
80+
- **failed/** - ZIP archives of failed analysis attempts with compile errors
81+
- **ctu_connections/** - Cross-translation unit analysis metadata
82+
83+
## Metadata Structure
84+
85+
The `metadata.json` file contains comprehensive information about the analysis run, including configuration, enabled checkers, and statistics.
86+
87+
### Field Descriptions
88+
89+
`Metadata format version : 2`
90+
91+
**Top-level fields:**
92+
- `version` - Metadata format version
93+
- `tools` - Array of tool configurations (typically one CodeChecker entry)
94+
95+
**Tool object fields:**
96+
- `name` - Tool name ("codechecker")
97+
- `action_num` - Number of compilation actions analyzed
98+
- `command` - Full command line used to invoke the analysis
99+
- `version` - CodeChecker version with git commit hash
100+
- `working_directory` - Project root directory where analysis was executed
101+
- `output_path` - Absolute path to report directory
102+
- `result_source_files` - Map of report files to their source files
103+
- `analyzers` - Configuration for each analyzer (clangsa, clang-tidy, cppcheck, gcc)
104+
- `skipped` - Number of skipped source files
105+
- `timestamps` - Analysis start (`begin`) and end (`end`) times in Unix epoch
106+
107+
**Analyzer object fields:**
108+
- `checkers` - Map of checker names to enabled status (true/false)
109+
- `analyzer_statistics` - Analysis results summary
110+
- `failed` - Count of failed analyses
111+
- `failed_sources` - List of source files that failed analysis
112+
- `successful` - Count of successful analyses
113+
- `successful_sources` - List of successfully analyzed source files
114+
- `version` - Analyzer version
115+
116+
### Example
117+
118+
```json
119+
{
120+
"version": 2,
121+
"tools": [{
122+
"name": "codechecker",
123+
"action_num": 3,
124+
"command": [
125+
"analyze",
126+
"-d", "default",
127+
"-e", "optin.taint",
128+
"--timeout", "300",
129+
"./src/file.c",
130+
"-o", "./reports"
131+
],
132+
"version": "6.28 (2281ca3ce898b1061063ded46b7754f5da6281f5)",
133+
"working_directory": "/workspace/project",
134+
"output_path": "/workspace/project/reports",
135+
"result_source_files": {
136+
"/workspace/project/reports/file.c_clangsa_abc123.plist": "/workspace/project/src/file.c"
137+
},
138+
"analyzers": {
139+
"clangsa": {
140+
"checkers": {
141+
"optin.taint.GenericTaint": true,
142+
"optin.taint.TaintedAlloc": true,
143+
"core.NullDereference": false,
144+
"core.DivideZero": false
145+
},
146+
"analyzer_statistics": {
147+
"failed": 0,
148+
"failed_sources": [],
149+
"successful": 3,
150+
"successful_sources": [
151+
"/workspace/project/src/file.c"
152+
],
153+
"version": "20.0.0"
154+
}
155+
}
156+
},
157+
"skipped": 0,
158+
"timestamps": {
159+
"begin": 1770915554.200186,
160+
"end": 1770915561.956268
161+
}
162+
}]
163+
}
164+
```
165+
166+
## Report File Structure
167+
168+
For detailed plist format specification, see [plist.md](tools/plist.md).
169+
170+
### Success Report (.plist)
171+
172+
```xml
173+
<plist>
174+
<dict>
175+
<key>diagnostics</key>
176+
<array>
177+
<dict>
178+
<key>check_name</key>
179+
<string>cert-err33-c</string>
180+
<key>description</key>
181+
<string>Issue description</string>
182+
<key>category</key>
183+
<string>cert</string>
184+
<key>location</key>
185+
<dict>
186+
<key>line</key><integer>564</integer>
187+
<key>col</key><integer>5</integer>
188+
<key>file</key><integer>0</integer>
189+
</dict>
190+
<key>path</key>
191+
<array><!-- Execution path --></array>
192+
</dict>
193+
</array>
194+
<key>files</key>
195+
<array><!-- Source file paths --></array>
196+
</dict>
197+
</plist>
198+
```
199+
200+
### Error Report (.plist.err)
201+
202+
```xml
203+
<plist>
204+
<dict>
205+
<key>analyzer_cmd</key>
206+
<array><!-- Full analyzer command --></array>
207+
<key>analyzer_name</key>
208+
<string>clang-tidy</string>
209+
<key>return_code</key>
210+
<integer>1</integer>
211+
<key>stderr</key>
212+
<string>Error messages</string>
213+
<key>stdout</key>
214+
<string>Warnings and errors</string>
215+
</dict>
216+
</plist>
217+
```
218+
219+
## Usage
220+
221+
1. **View reports:** Use CodeChecker web interface or CLI
222+
2. **Parse results:** Read plist files programmatically
223+
3. **Apply fixes:** Use YAML files in `fixit/` directory
224+
4. **Filter issues:** Query by checker name, severity, or file
225+
226+
## Common Issue Categories
227+
228+
- **cert** - CERT C/C++ coding standards
229+
- **bugprone** - Bug-prone code patterns
230+
- **cppcoreguidelines** - C++ Core Guidelines violations
231+
- **clang-diagnostic** - Compiler warnings
232+
- **performance** - Performance issues
233+
- **readability** - Code readability concerns

0 commit comments

Comments
 (0)