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

[Matthew Brush]

On 08/17/2011 07:01 PM, Lex Trotman wrote:
> On 18 August 2011 04:34, Matthew Brush<mbrush at codebrainz.ca>  wrote:

> [...]
>
> You may be using functions that are not in the API?  I see some more
> detail is needed, the way I understand it is meant to work is:
>
> geanyplugin.h includes geanyfunctions.h which defines a macro for each
> function in the interface, thus hiding the actual function.  Those
> macros map the function name to a call via a pointer member of the
> geanyfunctions structure.  Since structure members are not checked by
> dlopen this means it should not check for any Geany functions when
> opened.  If it is telling you that there are undefined functions then
> you are using functions directly not via the geanyfunctions structure.
>   It may also be possible that there are functions documented as being
> in the API that are not in geanyfunctions, but thats a bug (either
> undocument or add to geanyfunctions).  The pointers in the geany
> functions structure have full prototypes so the compiler can check
> them.
>
> To get the structure declarations, geanyplugin.h includes Geany
> headers, so functions that are not in the interface are unfortunately
> made visible to the compiler. This is why the insistence on only using
> the things documented (and so in geanyfunctions), even if others are
> visible.  This can't be fixed until we remove access to structures eg
> using getter/setter functions instead, and so remove the requirement
> for the Geany headers.
>
> This means that your plugin must be compiled against a version of
> Geany that has the functions you use in the interface, so the compiler
> can resolve the structure offsets.  But so long as it is ABI
> compatible it can be loaded into any version of Geany with at least
> your *minimum* API, which you set to not include those functions that
> you can avoid using, based on the runtime version of the API.  If only
> you could get the runtime version of the API.
>

That was *extremely* useful information, you should put that on the Wiki 
too :)

>>
>> IMO, it's quite useful/important that each function/member's doc-comments be
>> annotated with the API version number as well, as has been discussed.  This
>> would let developers reading the API docs know *exactly* which API version
>> they should check against to use a certain thing, even between releases.
>>
>
> I agree, I find that the "since" info in things like GTK is
> invaluable, and I swear at any entries without it.
>

For sure, and it's super easy to do, since changes are usually done bit 
by bit, it's literally an extra 30 seconds of time to add this 
information in the doc-comment.

>
> But perhaps they could be wrapped in a PLUGIN_DECLARE macro or similar.
>

Would that just insert the prototypes for all the functions right into 
the source file where that macro is?

Cheers,
Matthew Brush