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

Nick Treleaven nick.treleaven at xxxxx
Wed Oct 28 11:00:41 UTC 2009


On Wed, 28 Oct 2009 10:56:30 +1100
Lex Trotman <elextr at gmail.com> wrote:

> >> The documented functions in build.h were intended to be added to the
> >> API after discussions with Enrico in the past.  Not sure why they
> >> weren't.  What needs to be done to do that?
> >
> > Sorry I hadn't raised this before.
> >
> > Basically there are 2 issues:
> >
> > 1. The proposed build API is not designed to be developed in future
> > without breaking the ABI.
> 
> Hmmm not sure why, the functions in the interface take enums or
> integers, the plugins don't index arrays directly.
> So long as enums and the GeanyBuildCommand structure are only extended
> I think it will be ABI compatible and it will be API compatible if new
> fields are added, the only thing you can't do is remove enums or
> fields or change their meaning or type and that restriction is always
> going to exist on anything visible in the API, like GeanyFiletype :-)

I should have been clearer - I haven't really studied the build API,
but a potential ABI problem is that GeanyBuildCommand has:

gchar 	*entries[GEANY_BC_CMDENTRIES_COUNT];

What if we want to increase GEANY_BC_CMDENTRIES_COUNT - we'd have to
break the ABI.

> The only way of getting around this is to make all the interface via
> functions/macros and don't expose any enums or structures.  But thats
> a lot of work for limited gain and would probably affect other parts
> of the API more than build.
> 
> See:
> > http://geany.org/manual/dev/hacking.html#plugin-api-abi-design
> >
> > BTW, I only wrote that after you designed the build API ;-)
> >
> > 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).

What do you mean by structure invariants?

> > 2. Not sure if the proposed API functions are the best/tidiest way to do
> 
> Thats true, I only tried to provide a minimal interface to avoid the
> problems of backward compatibility, but not sure if its necessary or
> sufficient.
> 
> > it, it would be best if there was a plugin that wanted to use these
> > functions so we can see what is needed. We need to avoid wanting an API
> > change in future, this is much more important than breaking the ABI.
> > Also the build code still hasn't been tested in a release; not sure if
> > we want to change the implementation (maybe not),
> 
> You must be psychotic ... ermm psychic I mean :-), to get a cleaner
> implementation so that the UI is cleaner I am looking at some changes
> to GeanyBuildCommand, but only additions (so far).  Oh, and I'm sure
> you'll be pleased that I no longer jam two small integers into
> user_data. So lets leave things out of the API it until a plugin
> builder asks.

OK, sounds good. Don't worry too much about reworking things, we can
always provide getter/setter functions to avoid exposing any ugly/ABI
brittle things if needed.

Regards,
Nick



More information about the Devel mailing list