Versioning & Compatibility
How kbox-stack is versioned, how to read the version at compile time, and the ABI and toolchain rules that govern mixing the prebuilt static library with your firmware.
kbox-stack ships as a prebuilt static library plus public headers. The
version identifies both the API in the headers and the ABI of the compiled .a.
Version scheme
Versions are MAJOR.MINOR.PATCH.BUILD.
| Field | Meaning |
|---|---|
MAJOR | Incompatible public-API or ABI change. |
MINOR | Backward-compatible feature additions. |
PATCH | Backward-compatible fixes. |
BUILD | Auto-incremented build counter (bumped on mainline commits); not a semantic field. |
The version header is generated at build time and published into
dist/include/Stack/StackVersion.h, so a consumer always compiles against the
exact version of the .a it links.
Reading the version at compile time
The header exposes four numeric macros plus a ready-made string. Use them to gate features or to print the linked stack version at boot.
#include <Stack/StackVersion.h>
// Numeric fields:
// KBOX_STACK_VERSION_MAJOR
// KBOX_STACK_VERSION_MINOR
// KBOX_STACK_VERSION_PATCH
// KBOX_STACK_VERSION_BUILD
// Combined string:
// KBOX_STACK_VERSION_STRING // e.g. "1.0.0.0001"
#if (KBOX_STACK_VERSION_MAJOR > 1) || \
(KBOX_STACK_VERSION_MAJOR == 1 && KBOX_STACK_VERSION_MINOR >= 1)
// A 1.1+ feature is available.
#endif
const char* stackVersion = KBOX_STACK_VERSION_STRING;The value of KBOX_STACK_VERSION_STRING is set by the build that produced the
.a you received. Read it from your linked header — do not hard-code it in
application logic.
ABI & toolchain compatibility
The .a is compiled with a specific target, ABI, and set of compile-time knobs.
Your firmware must be built compatibly, or the link is unsafe even when it
succeeds.
Consumer build flags must match the prebuilt .a. In particular:
- Target/ABI — the shipped binary is Cortex-M3 / STM32F103xB. Binaries
are produced per platform; you cannot link the Cortex-M3
.ainto a different core. Moving to another MCU means a rebuilt binary — see Porting. KNX_APDU_MAX— this knob changes struct sizes and the storage-buffer sizes (KBOX_STACK_STORAGE_SIZE,KBOX_SECURE_STORAGE_SIZE). It must be identical in your build and in the build that produced the.a.- Compiler / C++ standard /
-DNDEBUGand other ABI-affecting flags must be consistent across your objects and the library.
The byte-parity guardrail: the stack is compiled with no project-specific
defines (AC_UNIT_*, APP_TYPE_*, …). The same .a is byte-identical across
consumer projects on the same target. Do not expect a project define to change
stack behaviour.
Upgrading between versions
Read the Changelog for the target version and note any
MAJOR bump — that flags an API/ABI break to plan for.
Replace both the .a and the dist/include/Stack/ headers together. Never
mix headers from one version with a library from another.
Re-check KBOX_STACK_VERSION_STRING at boot to confirm the version you intended
is the one linked.
Re-verify your table sizes and storage buffers. If KNX_APDU_MAX changed, the
storage struct sizes changed too; re-confirm StackParameters table sizes still
fit your ETS project.