As lead of a C++ plugin SDK shipped as a shared library to third parties, what ABI-stability policy do you set across releases?
answer
- who must rebuild, and how often
- C boundary or pinned C++ toolchain
- hidden by default, export on purpose
- version check at plugin load
- breaks only in a major release
basics
~20 sDecide what you promise and enforce it: a C-linkage boundary with opaque handles for any toolchain, or a pinned C++ toolchain with pimpl'd classes; hidden-by-default symbols, a load-time ABI version check, CI symbol diffs and breaks only in major releases.
solid answer
~40 sFirst decide the promise. If third parties build with compilers you do not control, put an `extern "C"` boundary in front: opaque handles, functions instead of member access, plain structs that carry a size or version field, error codes instead of exceptions, and a header-only C++ wrapper compiled into each plugin. If you can mandate one compiler, standard library and ABI settings, a C++ interface is viable, but only with pimpl'd classes, no inline code touching layout and append-only rules reviewed on every header diff. Either way: build with hidden visibility and export only the documented API, have plugins report the ABI version they were built for so the host refuses mismatches, diff exported symbols in CI against the last release, and confine breaks to major versions with a published deprecation window.
code
cpp · 6 lines#define SDK_API __attribute__((visibility("default")))
namespace sdk {
int helper(int x) { return x * 3; } // hidden under -fvisibility=hidden
SDK_API int plugin_entry(int x) { return helper(x) + 1; }
}
extern "C" SDK_API int sdk_abi_version() { return 3; }go deeper
Know that a shared library used by others must keep its binary interface stable, and that extern "C" functions are the most portable way to do it.
Explain opaque handles, hidden-by-default visibility with explicit exports, and why exceptions must not escape a C-linkage entry point.
Set up the controls: a version handshake at load, a CI symbol diff, header review for silent breaks and pimpl for any C++ classes kept public.
Pick the promise – C boundary, pinned toolchain or rebuild per release – by who pays the cost, and define when a major version may break it.
## Start from the promise An ABI policy answers one question for plugin authors: **when must I rebuild?** The possible answers carry very different costs: | Promise | Boundary | Cost to the SDK team | Cost to plugin authors | |---|---|---|---| | Never, within a major version, on any supported compiler | `extern "C"` functions, opaque handles, plain structs | Boilerplate, a wrapper layer, no exceptions across the line | None until the next major | | Never, if you use our exact toolchain | C++ classes with pimpl and strict review | Review discipline, toolchain pinned for everyone | Must match compiler, standard library and flags | | Every release | Anything | Minimal | Rebuild on every upgrade | A studio that writes all its own plugins can choose the third row. A product with a marketplace of third-party plugins realistically needs the first, because it cannot dictate the compiler of a stranger's build. ## The C boundary in detail The platform's C calling convention and struct layout rules are shared by the compilers on that platform, and C-linkage symbols are not mangled, which is why the "hourglass" design works: 1. **Opaque handles.** `typedef struct sdk_mixer sdk_mixer;` with `sdk_mixer* sdk_mixer_create(void);` and `void sdk_mixer_destroy(sdk_mixer*);`. The plugin never sees a layout, so the SDK can change it freely. 2. **Functions instead of fields.** `sdk_mixer_set_volume(m, 7)` rather than a public member. 3. **Extensible structs.** When a struct must cross, its first field is its own size or a version number, and new fields only go at the end. 4. **No exceptions across the line.** Every `extern "C"` entry point catches everything and returns an error code; C++ code with C linkage can still throw, so this is a rule you enforce, not one the language gives you. 5. **A C++ veneer.** A header-only C++ wrapper with RAII classes is compiled into each plugin, so authors keep a comfortable API while only C shapes cross the boundary. ## If the boundary stays C++ Then the policy is a list of rules applied to every header change: classes are pimpl'd so `sizeof` is fixed; no inline function reads data members; virtual interfaces are frozen, and new virtual functions go into a new interface class rather than an existing one; default arguments and enumerator values do not change; and the supported toolchain is documented down to the standard library and its ABI macro (`_GLIBCXX_USE_CXX11_ABI` on libstdc++). Exception types thrown into plugins need default visibility so that `type_info` is shared between shared objects, which GCC's documentation calls out. ## Controls that apply to both - **Hidden by default.** Build the SDK so that symbols are hidden unless marked, and mark the public API with `__attribute__((visibility("default")))` behind a macro. GCC's documentation strongly recommends this for any distributed shared object and notes it should be viewed as part of the API contract. The ABI surface then shrinks from every symbol to the documented ones, so internal refactors stop being potential breaks. The exact flags belong to the toolchain material on linking. - **A version handshake.** Each plugin exports `extern "C" int plugin_abi_version(void)` returning the SDK version it was built for; the host checks it before calling anything else and refuses a plugin from another major version. - **A symbol diff in CI.** Store the list of exported symbols for each release and fail the build when one disappears or changes; pair it with a header review checklist for the silent breaks a symbol list cannot see. - **Versioned breaks.** Breaks happen only in a major release, announced with a deprecation window, and the shared library's version changes with them so an old plugin cannot load the new library by accident. Inline namespaces are another way to version C++ symbols, covered with namespaces. ## Making the call The judgement is not technical correctness – every option above works – but who pays. A C boundary moves cost onto the SDK team permanently. A pinned toolchain moves it onto every plugin author at every compiler upgrade. Rebuild-every-release moves it onto the ecosystem's goodwill. A lead picks based on how many plugin authors exist, how much control the business has over them, how long releases must stay compatible, and how often the team expects to change the internals.
- Why does hidden-by-default visibility matter for ABI rather than just for load time?Every exported symbol is something a plugin might bind to, so with everything public an internal helper's signature change can break a plugin that should never have used it. Exporting only the documented API makes the ABI surface the API you meant to promise, which also makes a CI symbol diff meaningful.
- How do you add a feature to a C-boundary SDK without breaking old plugins?Add new functions rather than changing old ones, append fields to versioned structs and check their size field, and let the host query the plugin's ABI version before using anything new. Old plugins never call the new functions, so they keep working.
- A C++ class interface is stable as long as we never remove methods.
- Visibility settings only affect load time, not compatibility.
- extern "C" makes the compiler stop exceptions at the boundary.
- If our compiler is backward compatible, plugin authors can use any compiler.
- We can fix ABI problems later with a patch release.