[Tile-dev] Stubs table

[Joe E. <jen...@fl...>]

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...