Skip to content

ABI/API Compatibility — A Learning Series

Numbered steps, from "what is an ABI?" through checking a multi-binary product in CI to what no static check can decide. Steps 1–5 are about the problem and the promise you are making; from Step 6 on they are about catching breaks, which is where checking tools such as abicheck become the subject. Read the steps in order — each assumes the ones before it — and follow the Ladder line at the bottom of every page to the next one. The sidebar lists the same steps in the same order.

Start here

The path

  1. Start Here (beginner) — ABI in Five Minutes → How a Break Shows Up → ABI Cheat Sheet → Glossary
  2. Foundations (beginner → intermediate) — Part 0 — Compatibility as a Product Contract → Part 1 — Foundations → What Is Part of Your ABI Surface?
  3. How Breaks Happen (intermediate) — Part 2 — Symbol Contract Breaks → Part 3 — Type Layout Breaks → Part 4 — C++ ABI Specifics (go deeper: Class Layout ABI & API, Exception Unwinding, Modern C/C++ and Toolchain ABI Hazards) → Part 5 — ELF & Linker-Level Concerns (go deeper: The MSVC/PE ABI Model) → Part 6 — Subtle & Transitive Breaks
  4. Designing for Stability (intermediate) — Part 7 — Designing for Stability
  5. Define Your Contract (intermediate) — Compatibility Direction → Consumer Models → Build Profile Comparability → Static & Header-Only Contracts — also: Contract-Aware Compatibility (Concepts tab)
  6. Detect Breaks (intermediate) — Detecting Breaks → Assurance Beyond Static Checking — also: Evidence & Detectability (Concepts tab); What Each Level Sees (Concepts tab)
  7. In Practice (intermediate) — Where in the Pipeline → Report the Surface, Not Only the Breaks → Rollout and Governance → Triage a Suspicious Finding — also: Baseline Management (tool guide)
  8. At Scale (advanced) — Products, Not Libraries → Template- and Header-Heavy Libraries → How System Libraries Stay Compatible → Dependency & Runtime Floors → Environment & Toolchain Drift → Packages and Consumers
  9. Beyond Static ABI (advanced) — Behavioral & Semantic Compatibility → Data, Wire & Storage Compatibility → Ownership & Lifetime Contracts → Concurrency & Initialization Contracts

Concepts tab — the tool's own sequence

A "go deeper" page is an optional side read; it returns you to the step it hangs from. An "also" page belongs to another tab but is worth reading at that point.

Shortcuts by role

Each shortcut walks the steps in order, skipping what the role does not need, and ends with the tool page to open next.

Role Read, in order (step · page) Then
New C/C++ library author 1 · ABI in Five Minutes → 1 · How a Break Shows Up → 2 · Part 0 — Compatibility as a Product Contract → 2 · Part 1 — Foundations → 3 · Part 2 — Symbol Contract Breaks → 3 · Part 3 — Type Layout Breaks → 4 · Part 7 — Designing for Stability Choose Your Workflow
C++ library maintainer 2 · Part 1 — Foundations → 3 · Part 4 — C++ ABI Specifics → 3 · Class Layout ABI & API → 3 · Part 6 — Subtle & Transitive Breaks → 4 · Part 7 — Designing for Stability → 8 · Template- and Header-Heavy Libraries Choose Your Workflow
CI / release engineer 1 · How a Break Shows Up → 5 · Compatibility Direction → 6 · Detecting Breaks → 7 · Where in the Pipeline → 7 · Report the Surface, Not Only the Breaks → c1 · Verdicts Choose Your Workflow
Distribution / package maintainer 3 · Part 5 — ELF & Linker-Level Concerns → 8 · Products, Not Libraries → 8 · How System Libraries Stay Compatible → 8 · Dependency & Runtime Floors → 8 · Packages and Consumers Choose Your Workflow
Product / SDK owner (several binaries) 2 · Part 0 — Compatibility as a Product Contract → 5 · Consumer Models → 7 · Where in the Pipeline → 8 · Products, Not Libraries → 8 · Template- and Header-Heavy Libraries Choose Your Workflow
Plugin / SDK author 3 · Part 2 — Symbol Contract Breaks → 4 · Part 7 — Designing for Stability → 5 · Compatibility Direction → 5 · Consumer Models → 7 · Rollout and Governance Choose Your Workflow
AI agent / automated reviewer 1 · How a Break Shows Up → 7 · Triage a Suspicious Finding → c1 · Verdicts → c2 · Evidence & Detectability Output Formats

ABI and API, defined

  • ABI (Application Binary Interface) — the binary-level contract between a compiled library and its consumers: symbol names, calling conventions, struct/class layout, vtable order. Changing it can break already-compiled callers without anyone recompiling.
  • API (Application Programming Interface) — the source-level contract (declarations, signatures, semantics) a caller compiles against. Changing it can break recompilation even when the ABI is intact.

The two overlap but neither contains the other: a renamed enum member breaks the API and leaves the ABI alone; a reordered struct field breaks the ABI and leaves the API alone. Examples are ELF/Linux and Itanium-C++-ABI flavoured unless a page says otherwise; Part 5 carries the PE/COFF and Mach-O parallels and the Platform Support reference the exact matrix.

After the series