Hi All,
Given that the previous thread had moved way off topic, I started this one.
After thinking about it a bit, considering Matthew's, Colomban's and Thomas's comments and looking at other systems I came to the understanding documented below. Frank probably already knew all this, but I have saved him writing lots of English. If its right and you think its worth using in the newsletter or anywhere else feel free to copy it.
Background ---------------
Starting at first principles, the purpose of version checking with plugins is:
1. to ensure the version of the plugin is likely to work as intended with the version of Geany, and
2. to increase convenience by not requiring plugin re-compilation every time Geany changes.
Note that item two is a convenience for developers but is an essential for users of packaged releases, otherwise no plugins would work between release of a packaged version of Geany and release of new packaged versions of the plugins.
In more detail this requires that:
1. Geany provides at least the functions that the plugin requires, and
2. those functions continue to work the same, that is the plugin doesn't need any changes, including re-compilation
Different stakeholders also have different needs and views of the process:
1. Plugin developers need to know the exact point that Geany provides the functions that the plugin needs, they can't wait for releases and they are always re-compiling.
2. Plugin packagers need to know which Geany is required for the plugin(s) they are packaging so they can set dependencies, but their view is only of the Geany package version number.
3. Users want to be able to upgrade Geany from their package repo and still have installed plugins work if its safe for them to do so.
The Geany plugin interface version system provides a reasonable match to these requirements providing some rules are met.
How it works ----------------
The Geany plugin interface is characterised by two numbers:
1. the API number which represents the set of functionality that Geany provides.
2. the ABI number that ensures that the plugin is compilation compatible, ie compilation is not required
Functionality can be carefully appended to the interface (changing the API number) without changing how existing plugins use the interface (ie the ABI number).
Removals, inserts or changes of semantics require that the ABI be changed.
Having a single ABI number that represents the whole interface may require that a plugin be re-compiled even if the parts of the interface it uses havn't changed. This is a trade off between simplicity, reduction in human error and the flexibility of the interface.
These numbers have no relationship to release numbers, but each release has a specific API/ABI pair.
The system does not handle cross platform issues (Linux/Windows/Mac? or 32/64 bit) assuming that package systems will address this and users of non-packaged systems will likely re-compile anyway.
How to Use it -----------------
A plugin must have been compiled with a version of Geany with the same ABI as the one it is being loaded into. This ensures that nothing has been removed, no semantics have changed and none of the low level bit patterns have changed.
Geany must also supply at least the functions the plugin needs, so the API must be greater than that needed by the plugin.
These two checks are done by the PLUGIN_VERSION_CHECK macro.
The check is performed at runtime, but a plugin compiled against a version of Geany that is too old will still fail at compile time because of missing declarations.
Plugins that wish to use newer features but still support older versions can only make the decision at compile time because the API number of the Geany that the plugin is being loaded into isn't available at runtime. Making the API number available at runtime may be a potential enhancement of the interface and allow plugins to support a wider range of versions.
The API and ABI number pair should be published (in release notes?) when a release is made for use by plugin packagers.
Binary packagers of plugins should use the published API/ABI to define the versions of Geany required to be the intersection of the two sets of releases:
1. releases where the API number is greater than or equal to the greatest API required by a plugin in the package.
2. releases where the ABI number matches the ABI number of the Geany version the package is compiled with.
If these rules are complied with, users who use packages and users who compile can just let the system do its stuff. Developers *should* also find it just works (tm).
Developers of bindings to the Geany plugin interface should specify which API number they support (ie which features have been bound).
Implications ---------------
Because the ABI must match exactly, every effort must be made to limit changes that affect the ABI. Otherwise as soon as a new Geany is released all plugins stop working until re-compiled, and new packages are released, and installed by users. This is bad :-(
This means that:
1. the interface should be as small as possible so that the least possible changes impact the ABI.
2. structures should not be visible in the interface, instead they should be hidden behind getter/setter functions, and
3. interface wrapper functions should be used to hide the implementation and side effects.
The last two have not been Geany policy to date but I now propose that they be.
Feel free to throw bricks (or bouquets).
Cheers Lex