Extension Versioning (The GNU Awk User’s Guide)
Next: Extension GMP/MPFR Versioning, Up: Extension API Variables [Contents][Index]
17.4.13.1 API Version Constants and Variables
The API provides both a “major” and a “minor” version number. The API versions are available at compile time as C preprocessor defines to support conditional compilation, and as enum constants to facilitate debugging:
API Version | C Preprocessor Define | enum constant |
---|---|---|
Major | gawk_api_major_version
|
GAWK_API_MAJOR_VERSION
|
Minor | gawk_api_minor_version
|
GAWK_API_MINOR_VERSION
|
The minor version increases when new functions are added to the API. Such new functions are always added to the end of the API struct
.
The major version increases (and the minor version is reset to zero) if any of the data types change size or member order, or if any of the existing functions change signature.
It could happen that an extension may be compiled against one version of the API but loaded by a version of gawk
using a different version. For this reason, the major and minor API versions of the running gawk
are included in the API struct
as read-only constant integers:
api->major_version
- The major version of the running
gawk
. api->minor_version
- The minor version of the running
gawk
.
It is up to the extension to decide if there are API incompatibilities. Typically, a check like this is enough:
if ( api->major_version != GAWK_API_MAJOR_VERSION || api->minor_version < GAWK_API_MINOR_VERSION) { fprintf(stderr, "foo_extension: version mismatch with gawk!\n"); fprintf(stderr, "\tmy version (%d, %d), gawk version (%d, %d)\n", GAWK_API_MAJOR_VERSION, GAWK_API_MINOR_VERSION, api->major_version, api->minor_version); exit(1); }
Such code is included in the boilerplate dl_load_func()
macro provided in gawkapi.h
(discussed in Boilerplate Code).