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