diff --git a/docs/README.md b/docs/README.md index 35e31e1b4b..adde249b5f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -411,9 +411,12 @@ you should be greeted with a web application showing you the analysis results. ## Developer documentations * [Architecture](architecture.md) +* [Report Directory Specification](report_directory.md) +* [Plist Report Format Specification](tools/plist.md) * [Package layout](package_layout.md) * [Dependencies](deps.md) * [Thrift interface](web/api/README.md) +* [Sample CodeChecker Command Line Client](/scripts/thrift/README.md) * [Package and integration tests](tests.md) * [Server-side background tasks](web/background_tasks.md) diff --git a/docs/report_directory.md b/docs/report_directory.md new file mode 100644 index 0000000000..2df0ba412c --- /dev/null +++ b/docs/report_directory.md @@ -0,0 +1,220 @@ +# CodeChecker Report Directory Structure + +## Overview + +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`. + +Other tools, such as CodeChecker [bazel rules](https://github.com/Ericsson/rules_codechecker) should follow this specification to be compatible with the CodeChecker ecosystem. + +## Directory Layout + +``` +report_directory/ +├── metadata.json # Analysis metadata and configuration. (used opionally by store) +├── compiler_info.json # Compiler details and flags. (for debugging) +├── compile_cmd.json # Compilation commands. (for debugging) +├── unique_compile_commands.json # Deduplicated compilation commands (for debugging) +├── __.plist # Successful analysis results (used by parse and store) +├── __.plist.err # Analysis error logs (used by parse --status) +├── cppcheck/ # Cppcheck backup files +│ └── / +│ └── *.plist.bak +├── gcc/ # GCC analyzer backup files (for debugging) +│ └── *.sarif.bak +├── fixit/ # Clang-tidy fix suggestions (used optionall by store)) +│ └── *_clang-tidy_*.yaml +├── failed/ # Failed analysis artifacts (for debugging) +│ └── *_compile_error.zip +└── ctu_connections/ # Cross-translation unit data (for debugging) +``` +### Usage + +* `CodeChecker store` stores the reports found in the `plist` files and optionally parses the information in the `metadata.json`. + +* `CodeChecker parse` displays the reports in the `plist` files and displays analysis status based on the existence of the `plist` or `plist.err` files. + +* `CodeChecker parse --file` relies on the `result_source_files` section of the `metadata.json`. + +* `CodeChecker fixit` relies on the `fixit` subdirectory. +## File Types + +### Information files + +- **metadata.json** - Contains: + - CodeChecker version + - Analysis command + - Enabled analyzers and checkers + - Source file mappings + - Analysis statistics + +- **compiler_info.json** - Compiler configuration: + - Compiler path and version + - Include directories + - Language standard + - Target architecture + +- **compile_cmd.json** - Compilation database with build commands for each source file + +### Report Files + +Format: `__.plist` + +**Analyzers:** +- `clang-tidy` - C++ linter with 600+ checks +- `clangsa` - Clang Static Analyzer +- `cppcheck` - C/C++ static analyzer +- `gcc` - GCC static analyzer + +**Report Format:** Apple Property List (plist) XML containing: +- Diagnostics with severity, category, and description +- File locations (line, column) +- Execution paths showing issue flow +- Check names for filtering + +**Error Files** (`.plist.err`): +- Generated when analysis fails +- Contains analyzer command, return code, stderr, and stdout +- Includes compiler errors and warnings that prevented analysis + +### Auxiliary Directories + +- **fixit/** - YAML files with automated fix suggestions from clang-tidy +- **cppcheck/**, **gcc/** - Backup copies of original reports +- **failed/** - ZIP archives of failed analysis attempts with compile errors +- **ctu_connections/** - Cross-translation unit analysis metadata + +## Metadata Structure + +The `metadata.json` file contains comprehensive information about the analysis run, including configuration, enabled checkers, and statistics. + +### Field Descriptions + +`Metadata format version : 2` + +**Top-level fields:** +- `version` - Metadata format version +- `tools` - Array of tool configurations (typically one CodeChecker entry) + +**Tool object fields:** +- `name` - Tool name ("codechecker") +- `action_num` - Number of compilation actions analyzed +- `command` - Full command line used to invoke the analysis +- `version` - CodeChecker version with git commit hash +- `working_directory` - Project root directory where analysis was executed +- `output_path` - Absolute path to report directory +- `result_source_files` - Map of report files to their source files +- `analyzers` - Configuration for each analyzer (clangsa, clang-tidy, cppcheck, gcc) +- `skipped` - Number of skipped source files +- `timestamps` - Analysis start (`begin`) and end (`end`) times in Unix epoch + +**Analyzer object fields:** +- `checkers` - Map of checker names to enabled status (true/false) +- `analyzer_statistics` - Analysis results summary + - `failed` - Count of failed analyses + - `failed_sources` - List of source files that failed analysis + - `successful` - Count of successful analyses + - `successful_sources` - List of successfully analyzed source files + - `version` - Analyzer version + +### Example + +```json +{ + "version": 2, + "tools": [{ + "name": "codechecker", + "action_num": 3, + "command": [ + "analyze", + "-d", "default", + "-e", "optin.taint", + "--timeout", "300", + "./src/file.c", + "-o", "./reports" + ], + "version": "6.28 (2281ca3ce898b1061063ded46b7754f5da6281f5)", + "working_directory": "/workspace/project", + "output_path": "/workspace/project/reports", + "result_source_files": { + "/workspace/project/reports/file.c_clangsa_abc123.plist": "/workspace/project/src/file.c" + }, + "analyzers": { + "clangsa": { + "checkers": { + "optin.taint.GenericTaint": true, + "optin.taint.TaintedAlloc": true, + "core.NullDereference": false, + "core.DivideZero": false + }, + "analyzer_statistics": { + "failed": 0, + "failed_sources": [], + "successful": 3, + "successful_sources": [ + "/workspace/project/src/file.c" + ], + "version": "20.0.0" + } + } + }, + "skipped": 0, + "timestamps": { + "begin": 1770915554.200186, + "end": 1770915561.956268 + } + }] +} +``` + +## Report File Structure + +For detailed plist format specification, see [plist.md](tools/plist.md). + +### Success Report (.plist) + +```xml + + + diagnostics + + + check_name + cert-err33-c + description + Issue description + category + cert + location + + line564 + col5 + file0 + + path + + + + files + + + +``` + +### Error Report (.plist.err) + +```xml + + + analyzer_cmd + + analyzer_name + clang-tidy + return_code + 1 + stderr + Error messages + stdout + Warnings and errors + + +```