Skip to content

report_directory.md

Latest commit

 

History

History
220 lines (185 loc) · 7.12 KB

report_directory.md

File metadata and controls

220 lines (185 loc) · 7.12 KB

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 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)
├── <file>_<analyzer>_<hash>.plist      # Successful analysis results (used by parse and store)
├── <file>_<analyzer>_<hash>.plist.err  # Analysis error logs (used by parse --status)
├── cppcheck/                           # Cppcheck backup files
│   └── <hash>/
│       └── *.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: <source_file>_<analyzer>_<hash>.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

{
  "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.

Success Report (.plist)

<plist>
  <dict>
    <key>diagnostics</key>
    <array>
      <dict>
        <key>check_name</key>
        <string>cert-err33-c</string>
        <key>description</key>
        <string>Issue description</string>
        <key>category</key>
        <string>cert</string>
        <key>location</key>
        <dict>
          <key>line</key><integer>564</integer>
          <key>col</key><integer>5</integer>
          <key>file</key><integer>0</integer>
        </dict>
        <key>path</key>
        <array><!-- Execution path --></array>
      </dict>
    </array>
    <key>files</key>
    <array><!-- Source file paths --></array>
  </dict>
</plist>

Error Report (.plist.err)

<plist>
  <dict>
    <key>analyzer_cmd</key>
    <array><!-- Full analyzer command --></array>
    <key>analyzer_name</key>
    <string>clang-tidy</string>
    <key>return_code</key>
    <integer>1</integer>
    <key>stderr</key>
    <string>Error messages</string>
    <key>stdout</key>
    <string>Warnings and errors</string>
  </dict>
</plist>