Skip to content

abicheck

abicheck is a command-line tool that detects breaking changes in C/C++ shared libraries before they reach production. It compares two versions of a shared library — along with their public headers — and reports whether existing binaries will continue to work or break at runtime.

Typical problems it catches: removed or renamed symbols, changed function signatures, struct layout drift, vtable reordering, enum value reassignment, and 114 other ABI/API incompatibilities that cause crashes, silent data corruption, or linker failures after a library upgrade.

Platforms: Linux (ELF), Windows (PE/COFF), macOS (Mach-O). Binary metadata and header AST analysis on all platforms; debug info cross-check uses DWARF (Linux, macOS) and PDB (Windows).

Why abicheck

  • Three-layer analysis — ELF symbol table + Clang AST (via castxml) + DWARF cross-check — catches changes that no single layer detects alone
  • 114 detection rules — covers symbol removal, signature changes, struct/class layout drift, vtable reordering, enum value shifts, qualifier changes, and many more (see 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

Quick start

# Install
git clone https://github.com/napetrov/abicheck.git
cd abicheck && pip install -e .

# Compare two library versions
abicheck compare libfoo.so.1 libfoo.so.2 \
  --old-header include/v1/foo.h --new-header include/v2/foo.h

Exit codes (abicheck compare)

Exit code Verdict Meaning
0 NO_CHANGE / COMPATIBLE Safe — no breaking changes
1 — Tool/runtime error
2 API_BREAK Source-level API break (recompile needed, binary still works)
4 BREAKING Binary ABI break (old binaries will crash or misbehave)

abicheck compat uses ABICC-compatible exit codes (1 = BREAKING, 2 = API_BREAK). See Exit Codes for details.

CI integration

Save a baseline at release time, compare every new build:

- name: Compare ABI
  run: |
    abicheck compare abi-baseline.json ./build/libfoo.so \
      --new-header include/foo.h --format sarif -o abi.sarif

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: abi.sarif

Next steps

Status

CI