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.5.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.
• 396 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/SARIF output and a typed Python API for AI-driven workflows; agents use the CLI or the API directly, no separate protocol server.

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

Maintaining a public compatibility contract?

• Contract-Aware Compatibility — gate only on what you actually promised (public headers, exports, or everything).
• Contract Evaluation — the commands and CI recipes.

Checking multiple compilers and platforms?

• Scenario S17: Multiple Build and Compiler Profiles — a worked GCC + Clang + MSVC .abicheck.yml.
• Aggregate Reports — fold the matrix back into one gate, and tell a universal break from a profile-specific one.

Checking real applications and plugins?

• Application Compatibility — compare --used-by, including why a consumer depends on a changed declaration.
• Plugin Systems — compare --required-symbol.

Automating through Python or an agent?

• Python API — typed requests, and a CLI/Python parity table.

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