Examples & Case Encyclopedia¶
This catalog covers 105 cases demonstrating real-world ABI/API change scenarios for C/C++ shared libraries. Each case is a minimal compilable v1/v2 pair plus a consumer (app.c/app.cpp) that demonstrates the actual runtime effect.
Use this catalog to:
- Learn what kinds of changes break ABI vs. which are safe.
- See the runtime failure mode for each break (crash, wrong output, silent corruption…).
- Look up the mitigation pattern for a specific change.
- Cross-reference detected
ChangeKinds with concrete reproductions.
Ground truth. Expected verdicts and detected change kinds live in
examples/ground_truth.jsonand are the single source of truth — these pages are generated from that file plus per-caseREADME.mdfiles underexamples/.
Verdict distribution¶
| Verdict | Count | What it means |
|---|---|---|
| 🔴 BREAKING | 76 | ABI breaks: existing consumers will fail at runtime. |
| 🟠 API_BREAK | 4 | Source-level / API-only breaks; recompilation fails or behavior shifts. |
| 🟡 COMPATIBLE_WITH_RISK | 2 | Backward-compatible at the symbol level but with behavioral risk. |
| 🟢 COMPATIBLE | 20 | Backward-compatible changes (additions or quality-only). |
| ✅ NO_CHANGE | 3 | Identical ABI/API — baseline control cases. |
How to read a case page¶
Each case page starts with a metadata table (verdict, category, platforms, detected change kinds) followed by:
- What changes / what breaks — the source diff between v1 and v2.
- Why abicheck (or abidiff/ABICC) catches it — detection mechanism.
- Real Failure Demo — exact shell commands that reproduce the runtime effect.
- How to fix — the mitigation pattern, where the README documents one.
- Real-world example — historical occurrences in widely-used libraries.
- References — links to relevant standards, manuals, and abicheck source.
Source files (v1.*, v2.*, app.*, CMakeLists.txt) are linked at the bottom of every page.
Browse by category¶
| Category | Cases | What it covers |
|---|---|---|
| Breaking | 76 | Listed in BREAKING_KINDS — runtime ABI break. |
| API Break | 4 | Listed in API_BREAK_KINDS — source/API-level break. |
| Risk | 2 | Listed in RISK_KINDS — symbol-compatible but behaviorally risky. |
| Addition (Compatible) | 10 | Listed in ADDITION_KINDS — backward-compatible additions. |
| Quality (Compatible) | 10 | Listed in QUALITY_KINDS — metadata/quality issues, not ABI breaks. |
| No Change | 3 | Identical ABI/API — sanity-check baselines. |
All cases¶
| Case | Title | Verdict | Category |
|---|---|---|---|
| case01_symbol_removal | Symbol Removal | 🔴 BREAKING | Breaking |
| case02_param_type_change | Parameter Type Change | 🔴 BREAKING | Breaking |
| case03_compat_addition | Compatible Addition (New Export) | 🟢 COMPATIBLE | Addition (Compatible) |
| case04_no_change | No Change | ✅ NO_CHANGE | No Change |
| case05_soname | Missing SONAME | 🟢 COMPATIBLE | Quality (Compatible) |
| case06_visibility | Symbol Visibility Leak | 🔴 BREAKING | Breaking |
| case07_struct_layout | Struct Layout Change | 🔴 BREAKING | Breaking |
| case08_enum_value_change | Enum Value Change | 🔴 BREAKING | Breaking |
| case09_cpp_vtable | C++ Vtable Change | 🔴 BREAKING | Breaking |
| case105_concept_tightening | Concept Tightening (C++20) | 🟢 COMPATIBLE | Addition (Compatible) |
| case106_ctor_became_explicit | Conversion Operator Became explicit |
🟠 API_BREAK | API Break |
| case107_task_scheduler_init_removed | task_scheduler_init Removed (oneTBB historical break) |
🔴 BREAKING | Breaking |
| case108_task_class_removed | task Class Removed (oneTBB historical break — vtable angle) |
🔴 BREAKING | Breaking |
| case109_flow_graph_policy_renames | flow::graph Policy Tag Renames | 🔴 BREAKING | Breaking |
| case10_return_type | Return Type Change | 🔴 BREAKING | Breaking |
| case110_concurrent_unordered_map_api_drift | concurrent_unordered_map API Drift | 🔴 BREAKING | Breaking |
| case111_enumerable_thread_specific_lambda_ambiguity | enumerable_thread_specific Lambda-Init Ambiguity | 🟢 COMPATIBLE | Addition (Compatible) |
| case112_task_arena_attach_tag | task_arena::attach Tag Type Replaces Enum | 🔴 BREAKING | Breaking |
| case113_internal_template_signature_changed | case113 — internal function-template signature leaks via public API (BREAKING) | 🔴 BREAKING | Breaking |
| case114_cpo_kind_changed | case114 — CPO kind changed (BREAKING) | 🔴 BREAKING | Breaking |
| case115_api_depends_on_consumer_env | case115 — public API depends on consumer build environment (RISK) | 🟢 COMPATIBLE | Quality (Compatible) |
| case116_cxx_standard_floor_raised | NO_CHANGE) | ✅ NO_CHANGE | No Change |
| case117_experimental_graduated | case109 — experimental → stable graduation (compatible) | 🟢 COMPATIBLE | Addition (Compatible) |
| case118_experimental_removed_without_replacement | : removed without replacement (API break) | 🔴 BREAKING | Breaking |
| case119_inline_namespace_version_bumped | case112 — inline namespace version bumped (BREAKING) | 🔴 BREAKING | Breaking |
| case11_global_var_type | Global Variable Type Change | 🔴 BREAKING | Breaking |
| case12_function_removed | Function Removed from Shared Library | 🔴 BREAKING | Breaking |
| case13_symbol_versioning | Symbol Versioning Script | 🟢 COMPATIBLE | Quality (Compatible) |
| case14_cpp_class_size | C++ Class Size Change | 🔴 BREAKING | Breaking |
| case15_noexcept_change | Case 15 — noexcept Changed |
🟡 COMPATIBLE_WITH_RISK | Risk |
| case16_inline_to_non_inline | Case 16 — Inline → Non-inline (ODR / Symbol Appearance) | 🟢 COMPATIBLE | Addition (Compatible) |
| case17_template_abi | Case 17 — Template Instantiation ABI Change | 🔴 BREAKING | Breaking |
| case18_dependency_leak | Case 18 — Dependency ABI Leak | 🔴 BREAKING | Breaking |
| case19_enum_member_removed | Case 19 — Enum Member Removed | 🔴 BREAKING | Breaking |
| case20_enum_member_value_changed | Case 20 — Enum Member Value Changed | 🔴 BREAKING | Breaking |
| case21_method_became_static | Case 21 — Method Became Static | 🔴 BREAKING | Breaking |
| case22_method_const_changed | Case 22 — Method Const Qualifier Changed | 🔴 BREAKING | Breaking |
| case23_pure_virtual_added | Case 23 — Virtual Method Became Pure Virtual | 🔴 BREAKING | Breaking |
| case24_union_field_removed | Case 24 — Union Field Removed | 🔴 BREAKING | Breaking |
| case25_enum_member_added | Case 25 — Enum Member Added | 🟢 COMPATIBLE | Addition (Compatible) |
| case26_union_field_added | Case 26 — Union Field Added | 🔴 BREAKING | Breaking |
| case26b_union_field_added_compatible | Case 26b — Union Field Added (No Size Change) | 🟢 COMPATIBLE | Addition (Compatible) |
| case27_symbol_binding_weakened | Case 27 — Symbol Binding Weakened (GLOBAL → WEAK) | 🟢 COMPATIBLE | Quality (Compatible) |
| case28_typedef_opaque | Case 28 — Typedef and Opaque Type Changes | 🔴 BREAKING | Breaking |
| case29_ifunc_transition | Case 29 — GNU IFUNC Transition | 🟢 COMPATIBLE | Quality (Compatible) |
| case30_field_qualifiers | Case 30 — Field Qualifier Changes (const, volatile) | 🔴 BREAKING | Breaking |
| case31_enum_rename | Case 31 — Enum Member Rename | 🟠 API_BREAK | API Break |
| case32_param_defaults | Case 32 — Parameter Default Value Changes (C++) | ✅ NO_CHANGE | No Change |
| case33_pointer_level | Case 33 -- Pointer Level Change | 🔴 BREAKING | Breaking |
| case34_access_level | Case 34 — Access Level Changed | 🟠 API_BREAK | API Break |
| case35_field_rename | Case 35 -- Field Rename | 🔴 BREAKING | Breaking |
| case36_anon_struct | Case 36 -- Anonymous Struct/Union Change | 🔴 BREAKING | Breaking |
| case37_base_class | Case 37 -- Base Class Changes | 🔴 BREAKING | Breaking |
| case38_virtual_methods | Virtual Method Changes | 🔴 BREAKING | Breaking |
| case39_var_const | Variable Const Change | 🔴 BREAKING | Breaking |
| case40_field_layout | Field Layout Changes | 🔴 BREAKING | Breaking |
| case41_type_changes | Type-Level Changes | 🔴 BREAKING | Breaking |
| case42_type_alignment_changed | Type Alignment Changed (standalone alignas) | 🔴 BREAKING | Breaking |
| case43_base_class_member_added | Base Class Member Added | 🔴 BREAKING | Breaking |
| case44_cyclic_type_member_added | Cyclic Type Member Added | 🔴 BREAKING | Breaking |
| case45_multi_dim_array_change | Multi-Dimensional Array Element Type Change | 🔴 BREAKING | Breaking |
| case46_pointer_chain_type_change | Pointer Chain Type Change | 🔴 BREAKING | Breaking |
| case47_inline_to_outlined | Inline Function Moved to Outlined | 🟢 COMPATIBLE | Addition (Compatible) |
| case48_leaf_struct_through_pointer | Leaf Struct Change Propagated Through Pointer | 🔴 BREAKING | Breaking |
| case49_executable_stack | Executable Stack (GNU_STACK RWX) | 🟢 COMPATIBLE | Quality (Compatible) |
| case50_soname_inconsistent | SONAME Inconsistent (Wrong Major Version) | 🟢 COMPATIBLE | Quality (Compatible) |
| case51_protected_visibility | Protected Visibility (DEFAULT to PROTECTED) | 🟢 COMPATIBLE | Quality (Compatible) |
| case52_rpath_leak | RPATH Leak (Hardcoded Build Directory) | 🟢 COMPATIBLE | Quality (Compatible) |
| case53_namespace_pollution | Namespace Pollution (Generic Symbol Names) | 🔴 BREAKING | Breaking |
| case54_used_reserved_field | Used Reserved Field | 🟢 COMPATIBLE | Quality (Compatible) |
| case55_type_kind_changed | Type Kind Changed (struct → union) | 🔴 BREAKING | Breaking |
| case56_struct_packing_changed | Struct Packing Changed (pragma pack) | 🔴 BREAKING | Breaking |
| case57_enum_underlying_size_changed | Enum Underlying Size Changed | 🔴 BREAKING | Breaking |
| case58_var_removed | Global Variable Removed | 🔴 BREAKING | Breaking |
| case59_func_became_inline | Function Became Inline (outlined → inline) | 🔴 BREAKING | Breaking |
| case60_base_class_position_changed | Base Class Position Changed (Multiple Inheritance Reorder) | 🔴 BREAKING | Breaking |
| case61_var_added | Global Variable Added | 🟢 COMPATIBLE | Addition (Compatible) |
| case62_type_field_added_compatible | Type Field Added (Compatible — Opaque Struct) | 🟢 COMPATIBLE | Addition (Compatible) |
| case63_bitfield_changed | Bitfield Width Changed | 🔴 BREAKING | Breaking |
| case64_calling_convention_changed | Calling Convention Changed | 🔴 BREAKING | Breaking |
| case65_symbol_version_removed | Symbol Version Removed | 🔴 BREAKING | Breaking |
| case66_language_linkage_changed | Language Linkage Changed (extern "C" removed) | 🔴 BREAKING | Breaking |
| case67_tls_var_size_changed | TLS Variable Size Changed | 🔴 BREAKING | Breaking |
| case68_virtual_method_added | Virtual Method Added to Non-Virtual Class | 🔴 BREAKING | Breaking |
| case69_trivial_to_nontrivial | Trivially Copyable to Non-Trivial (Calling Convention Change) | 🔴 BREAKING | Breaking |
| case70_flexible_array_member_changed | Flexible Array Member Element Type Changed | 🔴 BREAKING | Breaking |
| case71_inline_namespace_moved | Inline Namespace Moved | 🔴 BREAKING | Breaking |
| case72_covariant_return_changed | Covariant Return Type Changed | 🔴 BREAKING | Breaking |
| case73_typedef_underlying_changed | Typedef Underlying Type Changed | 🔴 BREAKING | Breaking |
| case74_detail_base_class_changed | Internal detail:: base class layout change leaks via public API |
🔴 BREAKING | Breaking |
| case75_detail_embedded_by_value | Internal detail:: impl struct embedded by value |
🔴 BREAKING | Breaking |
| case76_detail_pimpl_vtable_changed | Internal detail:: polymorphic base vtable change |
🔴 BREAKING | Breaking |
| case77_detail_templated_base_changed | Internal detail:: templated base class layout change |
🔴 BREAKING | Breaking |
| case79_missing_template_instantiation | Missing template instantiation in shipped binary | 🔴 BREAKING | Breaking |
| case80_pimpl_shared_to_unique | Pimpl alias changed from shared_ptr to unique_ptr |
🔴 BREAKING | Breaking |
| case81_serialization_tag_reassigned | Serialization tag ID reassigned | 🔴 BREAKING | Breaking |
| case82_sycl_overload_set_removed | SYCL overload set removed (DPC++ build withdrawn) | 🔴 BREAKING | Breaking |
| case83_cpu_dispatch_isa_dropped | CPU-dispatch ISA family dropped | 🟡 COMPATIBLE_WITH_RISK | Risk |
| case84_bundle_soname_skew | Multi-library bundle SONAME skew | 🔴 BREAKING | Breaking |
| case86_tag_struct_renamed | Tag struct renamed (empty class re-mangling) | 🔴 BREAKING | Breaking |
| case87_default_template_arg_changed | Default template argument changed | 🔴 BREAKING | Breaking |
| case89_inline_accessor_renamed_pimpl_member | Inline accessor references renamed pimpl member | 🔴 BREAKING | Breaking |
| case94_empty_tag_gained_state | Empty Tag Gained State | 🔴 BREAKING | Breaking |
| case95_allocator_nested_typedef_removed | Allocator Nested-Typedef Removed | 🔴 BREAKING | Breaking |
| case96_hidden_friend_removed | Hidden Friend Operator Removed | 🟠 API_BREAK | API Break |