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