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

[Matthew Brush]

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.

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