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

[Lex Trotman]

2009/10/28 Nick Treleaven <nick.treleaven at btinternet.com>:
> 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.

Ok, true

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

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.

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

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

Ok, and they can keep the invariants true too.

>
> Regards,
> Nick
> _______________________________________________
> Geany-devel mailing list
> Geany-devel at uvena.de
> http://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel
>