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

[Lex Trotman]

Hi,

2009/10/27 Nick Treleaven <nick.treleaven at btinternet.com>:
> On Tue, 27 Oct 2009 07:48:27 +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 :-)

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).

>
> 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.

some of which may be
> exposed to the API.
>
> Regards,
> Nick
> _______________________________________________
> Geany-devel mailing list
> Geany-devel at uvena.de
> http://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel
>