Skip to content

Getting Started

abicheck compares two versions of a C/C++ shared library and tells you whether existing binaries will break. It supports ELF (Linux), PE/COFF (Windows), and Mach-O (macOS) binaries.

On all platforms it provides binary metadata analysis (exports, imports, dependencies) and header AST analysis (via castxml). Debug info cross-check uses DWARF on Linux (falling back to BTF/CTF when DWARF isn't present) and PDB on Windows; Mach-O has no debug-info cross-check today, so a headerless macOS input gets only binary metadata — header AST is available on any platform, Mach-O included, once you supply -H — see Platform Support for exactly what each platform sees without headers.

In CI already? Skip straight to the GitHub Action — it installs everything and runs the check in a few lines of YAML.

What question are you asking?

abicheck ships several commands; pick the one that matches your question. If you're unsure, start with abicheck compare — it's the default workflow.

Your question Command See
Did my library break? — does upgrading it break existing consumers? abicheck compare Run your first check
Does my application still work with the new library version? abicheck compare --used-by Application Compatibility
Did my whole package / release break? abicheck compare Multi-Binary Releases
Gate a pull request against a real baseline, with the deepest evidence available (headers + build + sources)? abicheck compare OLD NEW --depth source --since origin/main Evidence Depth
Will this binary load and resolve correctly in this sysroot — and does its dependency tree have unresolved symbols? abicheck deps tree (--sysroot /rootfs for a specific root) CLI Usage
Did anything in the dependency stack change between two sysroots / images? abicheck deps compare --old-root … --new-root … CLI Usage
Save a reusable ABI baseline for CI. abicheck dump Creating and Comparing a Baseline

For the full decision matrix — every artifact layout, accuracy tier, and CI policy — see Choose Your Workflow.

Your first five minutes

  1. ➡️ Install abicheck — conda-forge (recommended, bundles castxml) or a lightweight pip install.
  2. ➡️ Run your first check — compare two shared libraries from the repo's example catalog, then your own library.
  3. ➡️ Understand your first report — output formats and what the exit code means for CI.
  4. ➡️ Choose Your Workflow — once the basic flow works, map your actual artifacts/CI policy to the exact command.

Two other common day-one workflows, covered on their own canonical pages rather than here: saving a reusable baseline for CI (Creating and Comparing a Baseline) and checking whether an application (not just the library) still works after an update (Application Compatibility).

Next steps

Jump straight to your persona:

Background reading: