2009/10/28 Nick Treleaven nick.treleaven@btinternet.com:
On Wed, 28 Oct 2009 10:56:30 +1100 Lex Trotman elextr@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:
- 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.
- 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@uvena.de http://lists.uvena.de/cgi-bin/mailman/listinfo/geany-devel