|
From: Joe E. <jen...@fl...> - 2004-12-09 17:03:44
|
I'm (finally!) about to check in a stubs table interface for the tile package. I'm using a modified version of the core genStubs.tcl script, which does things a little bit differently. I'm hoping this will help avoid some of the ABI compatibility problems that the core has run into since the introduction of stubs. First change: The stub table has two new fields, "epoch" and "revision". The revision is simply the number of entries in the stub table. The epoch is incrememented each time there is an incompatible change to the ABI (typically this will only happen at major releases, but it can be bumped in between minor releases too if necessary). TTK_InitStubs(interp) will only succeed if the package version satisfies TILE_VERSION (as usual), the epoch number in the stubs table exactly matches that in ttkDecls.h, and the revision is greater than or equal the one in ttkDecls.h. The idea is to decouple the ABI version from the package version (which is generally considered good practice). The epoch number provides coarse-grained control and allows for completely incompatible changes, and the revision number provides fine-grained control (e.g., for when stubs table entries are added in a patch release or in the CVS HEAD). Second major change: the second argument to genStubs::declare is interpreted as a status guard instead of a platform guard. Possible values for the status field are: "current" (the default), "deprecated", and "obsolete". Declarations for deprecated stub entries are guarded by an #ifdef; declarations for obsolete entries are not generated at all. (Definitions are always generated; the status guard only affects the source API, not the stubs ABI). The idea here is to provide an easier upgrade path when entry points are deprecated; dependant packages should continue to compile with -DTTK_DEPRECATED while the extension author upgrades the code base to avoid deprecated functions. Tile will follow the policy that entry points will spend at least one release in the "deprecated" state before moving to "obsolete". There are a few other minor changes (like: no TCL_STORAGE_CLASS monkey business), but those two are the main ones. --Joe English jen...@fl... |