[Geany-Devel] Plugin API design question/change proposal

[Lex Trotman]

On 26 May 2014 09:10, Matthew Brush <mbrush at codebrainz.ca> wrote:
> Hi,
>
> If nobody's opposed to this, then I'll start working on it shortly. At worst
> we'll end up with some new `*private.h` files in the `src` directory and
> maybe find some buggy plugins and/or unintentionally-public API.
>
> I'll try to keep the private headers changes separate from the removal of
> the `geanyfunctions.h`/function pointer macros stuff, since in theory they
> are independent of each other.

To be clear, I support us cleaning up the API headers and moving to a
"single include" model like Glib/GTK.

Cheers
Lex

>
> Cheers,
> Matthew Brush
>
>
> On 14-05-20 02:29 AM, Matthew Brush wrote:
>>
>> Hi,
>>
>> Does anyone know why the plugin API was designed to use a bunch of
>> structures containing function pointers, hidden behind macros in
>> geanyfunctions.h? I found the commit where this stuff was added
>> initially (ie. plugin ABI 2-3) but it doesn't mention why it was done
>> like this and I tried to search the mailing list archives but Gmane
>> won't let me search and the other mailing list archive doesn't go back
>> that far.
>>
>> Somebody mentioned it might be because Windows doesn't export symbols by
>> default, but it still doesn't explain why this way chosen over
>> explicitly exporting the symbols using
>> __declspec(dllexport)/G_MODULE_EXPORT which, IIUC, does just this.
>>
>> As mentioned in the "Proxy Plugins" thread I'm looking into making the
>> headers scanned by GObject-introspection to automate binding the plugin
>> API to non-C plugins, but with all of the private stuff and public stuff
>> mixed together in public headers, it will be hard to do this.
>>
>> Assuming there isn't actually much of a reason for the chosen existing
>> function pointer/structure/macro mechanism, is anybody opposed to just
>> making the API available in the normal C way where the public functions
>> goes in one header that plugins (and core) can use, and one header where
>> the private stuff goes, that doesn't get installed?
>>
>> Just to see the work involved, I tried to do this with the build,
>> document and editor functions. It makes the public/private more
>> explicit, removes lots of extra code, makes only one place to update
>> when adding new functions to the API, doesn't force plugins to import a
>> bunch of private stuff indirectly by #including <geanyplugin.h>, still
>> makes the symbols available/exported on Windows, and does it without
>> breaking the official (ie. doxygen-commented) parts of the API (but it
>> would need an ABI bump). The experimental changes to build, document,
>> and editor functions are here in my header-cleanup-private branch, based
>> ontop of my "header-cleanup" branch that I have an open PR for:
>>
>> build.h/buildprivate.h
>>
>> https://github.com/codebrainz/geany/commit/0b1221ce85905a066adfaae62fc73470b34af4d5
>>
>>
>> document.h/documentprivate.h
>>
>> https://github.com/codebrainz/geany/commit/f5e03bbee2c4edc8fe66c8e0762ef86e1f130857
>>
>>
>> editor.h/editorprivate.h
>>
>> https://github.com/codebrainz/geany/commit/1534f196d626494b57d408f780dfde022f18dd07
>>
>>
>> What we could do for commonly used existing private stuff:
>>
>> https://github.com/codebrainz/geany/commit/ac02d5330af2bd2cfcff45609f0e5b02a8b9d72a
>>
>>
>> (Sorry, I just linked the relevant commits instead of the branch so
>> people don't have to figure out which specific ones I'm talking about
>> amidst all the other unrelated ones. It's mostly just to give an idea of
>> what I'm talking about.)
>>
>> I think this would be a fairly big improvement overall and it would
>> finally allow us to sort out what's really private and what's really
>> public, which will make bindings generated by scanning the headers much
>> easier.
>>
>> Some common stuff that wasn't public before (ie. doxygen-commented) but
>> that is still used in plugins could be added as "deprecated" to the
>> public header or if useful could be properly added with a doxygen
>> comment. This will avoid excessive breakage where plugins were using
>> private stuff.
>>
>> Any opinions, suggestions, reasons about the original design welcome.
>>
>> Cheers,
>> Matthew Brush
>> _______________________________________________
>> Devel mailing list
>> Devel at lists.geany.org
>> https://lists.geany.org/cgi-bin/mailman/listinfo/devel
>
>
> _______________________________________________
> Devel mailing list
> Devel at lists.geany.org
> https://lists.geany.org/cgi-bin/mailman/listinfo/devel