abicheck

abicheck detects breaking changes in C/C++ shared libraries before they reach production. Point it at two builds of a library (plus their headers), and it tells you whether existing binaries will keep working or break at runtime.

It supports ELF (Linux), PE/COFF (Windows), and Mach-O (macOS) binaries, and it's a drop-in replacement for abi-compliance-checker.

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.3.0
  with:
    old-library: abi-baseline.json
    new-library: build/libfoo.so
    new-header: include/foo.h

Why abicheck

• Three-layer analysis — ELF/PE/Mach-O symbol tables + Clang AST (via castxml) + DWARF/PDB cross-check. Each layer catches things the others miss.
• 254 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.
• ABICC drop-in — full flag parity for migrating from abi-compliance-checker.
• CI-ready — clear exit codes, SARIF upload, snapshot-based baselines, first-class GitHub Action.
• Agent-friendly — structured JSON, Python API, and an MCP server for AI-driven workflows.

How the documentation is organized

The docs are two complementary tracks, each ordered from introductory to expert:

1. Learn the problem — ABI/API Handling & Recommendations 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 with the learning series (part 0 assumes nothing; part 7 is expert-level design guidance) and keep the 129-case 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?

• ABI/API Handling & Recommendations — the consolidated guide.
• Learning series, part 0 — compatibility as a product contract, from first principles.
• ABI Cheat Sheet — which changes are safe, risky, or breaking, at a glance.

Evaluating or comparing tools?

• Tool Comparison & Benchmarks — abicheck vs abidiff vs ABICC on a pinned 74-case benchmark subset.
• Examples & Case Encyclopedia — generated pages for the single-library cases; bundle cases live under examples/.
• ABI/API Handling & Recommendations — real-world scenarios with code, plus design patterns that prevent each break.
• Limitations — what abicheck does not catch.

Integrating into a release pipeline?

• GitHub Action — ready-to-paste workflow.
• Output Formats — SARIF, JSON, HTML.
• Exit Codes — for gating CI.
• Policy Profiles and Suppressions.

Migrating from another tool?

• Migrating from ABICC
• Migrating from libabigail

Contributing or extending abicheck?

• Codebase Overview
• Testing Strategy
• Architecture Decision Records
• Project Goals & Status

Status