[Geany-Devel] Adding a plugin

Roger Booth rbooth at xxxxx
Sun Jun 9 09:22:32 UTC 2013

On 06/08/2013 04:13 AM, Lex Trotman wrote:
> On 8 June 2013 20:31, Roger Booth <rbooth at kabooth.com 
> <mailto:rbooth at kabooth.com>> wrote:
>     On 06/08/2013 03:02 AM, Frank Lanitz wrote:
>>     On Sat, 08 Jun 2013 02:54:38 -0700
>>     Roger Booth<rbooth at kabooth.com>  <mailto:rbooth at kabooth.com>  wrote:
>>>     One thing I could ask for is a reference in the docs to where I can
>>>     find the correspondence between api and abi. Maybe thats the wrong
>>>     question, but anyway, how do i know which abi version I need? This is
>>>     in regards to PLUGIN_VERSION_CHECK(xxx)
>>     A lot of functions have a note at Geany's API documentation, since
>>     which version of Geany they are avaialble. E.g. Since: 0.16 at
>>     utils_str_casecmp().
>>     Athttp://wiki.geany.org/plugins/development/api-versions  you can find
>>     also the connection between API and ABI as well as the corresponding
>>     Geany version.
>>     Cheers,
>>     Frank
>>     _______________________________________________
>>     Devel mailing list
>>     Devel at lists.geany.org  <mailto:Devel at lists.geany.org>
>>     https://lists.geany.org/cgi-bin/mailman/listinfo/devel
>     I guess what I was asking for was a note in the docs that talk
>     about writing plugins, and especially in the docs about
>     PLUGIN_VERSION_CHECK() that points to where the programmer can
>     read up on the connection between api and abi. Or at least how the
>     programmer can find out the number.
>     Its great that you tell me here, and I know that somewhere in my
>     mail history I have the info as well, but wouldn't it be better to
>     put the info at the location where it helps the the programmer
>     that is about to add a PLUGIN_VERSION_CHECK() to a plugin? That
>     was an issue for me, and adding the references to the location
>     where I was looking would have helped me.
>     But beyond that, let me understand. What I do when writing a
>     plugin is I keep track of the least value of x.yy in "Since: x.yy"
>     for every function I use from the Geany API. Then I look at the
>     URL you listed to find x.yy and cross reference it to an abi
>     number. And that abi number is the number I plug in to the
>     PLUGIN_VERSION_CHECK() macro. Is that how this works? If that is
>     so, again, maybe it would be nice to document the manual procedure
>     programmers should follow.
> It might be just a typo on your part, but it is the biggest A*P*I 
> number you get from the table that you plug into the version check. 
>  You don't do anything with the ABI number, its automatic.
> Or to be more realistic, plug in the API number of the geany you are 
> developing your plugin against. If you are using a function that is 
> too new for the Geany you are using you will get a compilation error. 
> So simply use the oldest version of Geany you want the plugin to work 
> for and sit back and let the compiler take the strain :)
> If you develop with a new version of Geany, then only when you are 
> *sure* your plugin is finished should you consider looking for the 
> oldest version of API that will work, therefore defining the oldest 
> version of Geany that will work.  But due to the unfortunate changes 
> of ABI that have happened every few versions, people will have to 
> compile your plugin themselves to use older Geany versions, so your 
> audience is narrowed significantly (those who use an older Geany but 
> are willing to compile plugins).  It is not possible to use a 
> precompiled plugin with a version of Geany that has a different ABI, 
> even if the API is ok.
>     Your initial post in this thread asked
>         Is there something that describes how to go about adding a
>     plugin to geany-plugins?
>     It sounded to me like you wanted to know about issues folks had
>     writing plugins. Well, I'm listing issues I have had writing Geany
>     plugins.
> Actually I wanted to know how to add them to the g-p build system, 
> rather than just plugins in general, since I havn't done anything g-p 
> before :)
> Since various people claim its just copying the examples in the docs 
> I'll see tomorrow :)
> But thanks for the feedback that it isn't clear how best to use the 
> API/ABI versions, thats the sort of info the experts need if they are 
> to be able to improve the docs.
> Cheers
> Lex
>     _______________________________________________
>     Devel mailing list
>     Devel at lists.geany.org <mailto: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

 From the Geany plugin website at

#define PLUGIN_VERSION_CHECK 	( 		api_required 	 ) 	


gintplugin_version_check  <http://www.geany.org/manual/reference/pluginsymbols_8c.html#a02238186945c26ea04e20410daf5b209>(gint abi_ver) \
     { \
         if  (abi_ver !=GEANY_ABI_VERSION  <http://www.geany.org/manual/reference/plugindata_8h.html#a81ace29a6d7fb7cce2b59100fe3f6d71>) \
             return  -1; \
         return  (api_required); \

Defines a function to check the plugin is safe to load.

This performs runtime checks that try to ensure:

  * Geany ABI data types are compatible with this plugin.
  * Geany sources provide the required API for this plugin.


        	/api_required/ 	The minimum API number your plugin requires.
        Look at the source for the value of |GEANY_API_VERSION| to use
        if you want your plugin to require the current Geany version on
        your machine. You should update this value when using any new
        API features.

The above documentation is crap.

First, note that the macro definition describes the parameter as 
abi_ver. So, according to the documentation, where does the sole 
parameter - abi_ver - come from?

So we can skip the test
     if(abi_ver blah blah)
unless somebody can answer the above question.

So that leads to the last line of code that generates stuff:
     return api_required;

I eliminated superfluous parens.

As documented, this macro returns what it is passed.

And you wonder why I'm confused?

BTW, this one is


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.geany.org/pipermail/devel/attachments/20130609/89253ff4/attachment.html>

More information about the Devel mailing list