Skip to content

abicheck

abicheck helps library and package maintainers understand and validate how their API/ABI evolves. Point it at two builds of a library (plus their headers) and it tells you what changed — additions, removals, modifications, dependency and deployment-requirement changes — whether existing binaries will keep working, which declared contract is affected (with --contract) and which known consumers (when you supply consumer binaries or use-case manifests), and what the supplied evidence could not establish. ABI/API compatibility analysis is the foundation; the vision records where the tool is going from there.

It supports ELF (Linux), PE/COFF (Windows), and Mach-O (macOS) binaries.

Gate ABI in CI in 5 lines. Drop the first-class GitHub Action into any workflow — it installs everything, runs the comparison, sets the exit code, and can upload SARIF to the Security tab:

- uses: abicheck/abicheck@v0.6.0
  with:
    old-library: abi-baseline.json
    new-library: build/libfoo.so
    new-header: include/foo.h

Why abicheck

  • Five-source evidence model — abicheck overlays up to five independent, additive sources (the binary, its debug info, its public headers, its build-system data, and optionally its sources — L0–L4), cross-checks them against each other (DWARF/PDB debug info against the symbol table, header AST against build flags), and lets the strongest evidence win. Each source catches breaks the others miss. See Evidence & Detectability.
  • 408 detection rules — symbol removal, signature changes, struct/class layout drift, vtable reordering, enum value shifts, qualifier changes, calling conventions, and many more. See the Change Kind Reference.
  • Multiple output formats — Markdown, JSON, SARIF (GitHub Code Scanning), HTML.
  • Policy profiles — strict_abi, sdk_vendor, plugin_abi, or custom YAML overrides.
  • CI-ready — clear exit codes, SARIF upload, snapshot-based baselines, first-class GitHub Action.
  • Agent-friendly — structured JSON/SARIF output and a typed Python API for AI-driven workflows; agents use the CLI or the API directly, no separate protocol server.
  • Additions are changes too — a compatible release still lists every new function, variable, and enumerator with a version-bump recommendation, so surface growth is reviewed, not assumed. See Verdicts.

Which workflow is yours?

One semantic model serves every scope below; picking one never makes the others prerequisites. Items marked planned describe direction recorded in the vision, not shipped behavior.

You have Start with
Two builds of one library (binaries, snapshots, or one of each), optionally with headers Getting Started, then CLI Usage — no package metadata, debug info, or consumer artifacts required
Two releases of a multi-library product or package Multi-Binary & Release Comparison and Choose Your Workflow
One local build to check against a multi-profile baseline Aggregate Reports for the per-profile story today; explicit selected-member matching against a multi-variant baseline is planned
A CI pipeline to gate GitHub Action or CI Gating — equivalent resolved requests decide the same way through the Action, CLI, and Python API (the Action and CLI also fold in .abicheck.yml and --pack; see Python API for the parity table)
Sources, build data, or known consumer binaries for deeper assurance Evidence Depth, Application Compatibility; a prebuilt-consumer lifecycle beyond a single supplied application is planned

How the documentation is organized

The docs are built from two complementary tracks, each ordered from introductory to expert — the "Where to go next" list below routes by task/ persona instead, for whichever track (or both) a given question actually needs:

  1. Learn the problem — ABI/API Compatibility is educational material that needs no abicheck knowledge: what ABI/API compatibility is, why libraries break their consumers, and how to design against it. Start at Step 1 — ABI in Five Minutes assumes nothing, and the overview page's numbered steps take you from there through checking a multi-binary product in CI — and keep the example encyclopedia as a catalog of real breaks.
  2. Use the tool — the User Guide takes you from install and first check through CI integration to specialised workflows; Concepts explains how abicheck works — what a verdict means, what each evidence source (binary, debug info, headers, build data, sources) can and cannot see, and how the pipeline is built; and Reference holds the exhaustive lookup tables (change kinds, exit codes, platforms, tool comparison).

Where to go next

New to abicheck?

  1. Getting Started — install, first check, CI setup.
  2. Choose Your Workflow — a decision guide that maps your artifacts and CI policy to the exact command.
  3. Verdicts — what each verdict means and how to react.
  4. CLI Usage — every command, every flag.

New to the ABI/API problem itself?

Evaluating or comparing tools?

  • Tool Comparison & Benchmarks — abicheck vs abidiff vs ABICC on a pinned 74-case benchmark subset.
  • Compatibility Catalog — a generated page for every one of the 197 calibration cases, navigable by rule, scenario kind, ecosystem, operation, evidence level, language, and verdict.
  • ABI/API Compatibility — real-world scenarios with code, plus design patterns that prevent each break.
  • Limitations — what abicheck does not catch.

Integrating into a release pipeline?

Maintaining a public compatibility contract?

Checking multiple compilers and platforms?

Checking real applications and plugins?

Automating through Python or an agent?

  • Python API — typed requests, and a CLI/Python parity table.
  • Agent Skills — three portable, triggerable skills (preview) a coding agent (Claude Code, Copilot, Codex, Cursor, Gemini CLI) loads to answer a compatibility question in the user's own words, no MCP server required. To enable them for everyone working in your repository, see Enabling skills in your repository.

Migrating from another tool?

Contributing or extending abicheck?

Status

CI PyPI version conda-forge