This is the official repository for the cppcheckdata-shims library. A "shim", by definition, is an API that adds new features to another, often extremely bare-bones library. In cppcheckdata.py, the Cppcheck API module for building plugins, we exactly have such thing.

cppcheckdata.py is solely responsible for parsing the XML 'dumpfile' that Cppcheck outputs for each Translation Unit, so its plugins to run wild. It parses the XML file into several Configuration objects, a 'configuration' being a single "semantically operational" form of the program --- and in fact, the term 'configuration' here is on lend from operational semantics.

Each Configuration holds with it:

• The processed token stream, Token (as opposed to the 'raw' token stream, also available);
• The functions of the Translation Unit, Function;
• The variables of the Translation Unit, Variable;
• The scopes of the Translation Unit, Scope;
• The value flow and values, ValueFlow;

This representation is extremely concrete. Although the Token object represnts, for expressions, an abstract syntax tree, it is neither intraprocedural, nor interporcedural, it is merely a representation of a single expression.

This library, housed in the cppcheckdata_shims library, is the main life force of this project. This plugin is a 'shim API' for cppcheckdata.py. It has over 20 modules (as of now) that add build on top of cppcheckdata.py. These modules provide intermediate representation, analysis tools, and tools for abstraction interpretation, symbolic execution, control flow analysis, data flow analysis, and so on. We also provide tools for reporting errors, scoring the code, etc.

Take a gander at MODULES.md to understand what each module does. cppcheckdata-shims is a fully-fledged static analysis library, with Cppcheck as its mere provenance.

The documentation is built using Sphinx. See doc/sphinx/README.md for detailed instructions.

$ cd doc/sphinx
$ make html

$ ./scripts/build-docs.sh

$ pip install -e ".[docs]"

• Shims Library: doc/sphinx/shims/

  • Overview of the 23 cppcheckdata_shims modules
  • API reference for core, dataflow, abstract interpretation, taint analysis, and model checking

• CASL Language: doc/sphinx/casl/

  • Language reference and syntax
  • Standard library documentation
  • Compilation and runtime guides

• Common Topics: doc/sphinx/common/

  • System architecture
  • Error handling
  • Contribution guidelines

Open the generated HTML in your browser:

$ open doc/sphinx/_build/html/index.html  # macOS
$ xdg-open doc/sphinx/_build/html/index.html  # Linux

A comprehensive manual is available in doc/vademecum/. This teaches users how to utilize the shims library and CASL language effectively.

LibLINT is a massive collection of addons for Cppcheck, all using the shims library. This library is growing and growing.

CASL stands for "Cppcheck Addon Specification Language". It is a S-Expression-based declarative constraint-based domain-specific language, used for specification of Cppcheck addons. A CASL file compiles directly to a Python program that uses the shims library.

pip install cppcheckdata-shims

import cppcheckdata
from cppcheckdata_shims import type_analysis, dataflow_analysis

# Parse a dump file
data = cppcheckdata.parsedump("program.c.dump")

# Run type analysis
for config in data.configurations:
    types = type_analysis.analyze(config)

# Run null pointer analysis
for config in data.configurations:
    analysis = dataflow_analysis.NullPointerAnalysis(config)
    analysis.run()
    results = analysis.get_results()

# Compile a CASL file to bytecode
casl compile analysis.casl

# Run the analysis on a dump file
casl run analysis.caslo --program program.c.dump

• Documentation: See doc/sphinx/ for full API documentation
• CASL Standard Library: casl/stdlib/ contains ready-to-use modules
• LibLINT Addons: liblint/ shows production-grade examples
• Erroneous Code: erroneous-code/ provides test cases for validation

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linters
ruff check .
mypy cppcheckdata_shims casl

# Format code
black cppcheckdata_shims casl tests

# Build documentation
./scripts/build-docs.sh

# Install development environment
./scripts/install-dev.sh