[Geany-devel] build API - Re: SF.net SVN: geany:[4367] trunk

[Nick Treleaven]

On Thu, 29 Oct 2009 08:56:42 +1100
Lex Trotman <elextr at gmail.com> wrote:

> >> > Not breaking the ABI is a goal of any future plugin API extensions, so
> >> > we don't have to rebuild all plugins so often.
> >>
> >> Excellent goal.
> >>
> >> In which case you might need to add that plugins should not save and
> >> restore structures since they may miss fields added later or fail to
> >> comply with changes to structure invariants required (neither of which
> >> will trigger an ABI/API step according to the doc).
> >
> > Not sure if I'm with you. Doesn't this cover it:
> > * Don't let plugins allocate any structs (stack or heap).
> 
> I was actually thinking about a plugin that tried to save and restore
> structure contents so it could restore values after running or save
> them to file for restore next time.  The struct might be allocated
> prior to the plugin being loaded.

I think plugins shouldn't try to do that. If it was necessary, we could
add functions to the API for any structures that need to be synced
from/to disk.

> > What do you mean by structure invariants?
> 
> Required relationships between members of structures, for example if
> GeanyBuildCommand has a non-null label it might reasonably require a
> non-null command and working directory to save checking all the time.
> (Note actually I think I test all of them all the time but its an
> example :-)
> 
> The API functions I provided all checked parameters then called
> internal versions that didn't.

Basically plugins probably shouldn't really set any of the exposed
struct fields, only read them. Maybe we should mark them as const but
I'm not sure if this would cause issues.

Anyway, we could improve the API docs (doxygen) to warn about these
things. (The HACKING file is for working on Geany's core).

Regards,
Nick