[Geany-Devel] Adding a plugin

[Roger Booth]

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
http://www.geany.org/manual/reference/plugindata_8h.html#a68c850fc7108c65909f4340da8c16df9

====================================================
#define PLUGIN_VERSION_CHECK 	( 		api_required 	 ) 	

*Value:*

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.

    *Parameters:*

        	/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

*Since:*
    0.19 




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