[Geany-devel] Plugin Version control (explained?)

[Lex Trotman]

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