Changes between Initial Version and Version 1 of CHowTo/BasicPluginHowto

Timestamp:

Jul 15, 2007, 10:43:47 PM (17 years ago)

Author:

John Bailey

Comment:

Migrate the C Plugin How-To from the doxygen stuff to the wiki

CHowTo/BasicPluginHowto

@@ +1 @@
+= C Plugin How-To =
+
+[[TOC(inline,noheading)]]
+
+== Introduction ==
+This How-To document is designed to provide a basic overview of writing a plugin for Pidgin, Finch, and/or libpurple in our native language, C.  We'll start with a basic "Hello, World!" plugin and go from there.  Let's dig in, shall we?
+
+As we've already stated, C plugins are native plugins.  They have complete access to all of the API provided by Pidgin, Finch, and libpurple.  This means that a C plugin can do basically anything it wants to do.  All our protocol plugins and our loader plugins (Mono, Perl, and Tcl) are written in C.
+
+== Getting Started ==
+To develop a plugin, you need to have an installation of libpurple that includes development headers, at minimum.  To write a plugin that includes features requiring Pidgin or Finch functionality, you will need to also have Pidgin or Finch installed, complete with development headers.
+
+It will actually be easier for the first-time plugin author to install the development dependencies and then have a copy of the corresponding Pidgin source tarball.  For example, if you're running 2.0.2 on a Debian Sid (unstable) or testing system, you would do the following:
+ {{{
+# apt-get build-dep pidgin
+ }}}
+
+Similarly, on a Fedora system, you would do this:
+ {{{
+# yum install pidgin-dev
+ }}}
+
+People using Windows should read the [wiki:BuildingWinPidgin Building Windows Pidgin] page on this wiki to set up the necessary build environment.
+
+The command above for Debian systems will install only the build dependencies of Pidgin, Finch, and libpurple.  The command shown for Fedora will install all of those, as well as the development headers for libpurple, Finch, and Pidgin.
+
+Once you have installed these dependencies, download a source tarball.  You will want to use the source tarball that matches the version of Pidgin you are running, as it's generally a good idea to compile against the same version you run your plugins with.
+
+For the purposes of this How-To, we will assume the following:
+  * You understand the concept of `~` being your home directory
+  * You are working within the directory `~/development`.
+  * You are using Pidgin 2.0.2.
+
+If you are using a different version of Pidgin, simply replace references to 2.0.2 with whichever version you are using.  If you wish to use a path other than `~/development` (for example, Windows users correctly following the instructions will have `~/win32-dev` and their Pidgin tarball will be extracted in `~` to match), simply treat our references to `~/development` as a reference to the directory in which you extract the tarball.
+
+Now, extract the tarball:
+ {{{
+~/development $ tar -jxvf pidgin-2.0.2.tar.bz2
+ }}}
+
+Next, change to the `pidgin-2.0.2` directory.  If you are using Windows, run `make -f Makefile.mingw` to build Pidgin.  If you are using another platform, run `./configure` and then `make` after the configuration is complete.  You may wish to customize the arguments to the configure script, which is beyond the scope of this document.  '''If you are using Windows, DO __''NOT''__ under any circumstances use the configure script!  Any executables or .dll files derived from a Pidgin tree that has been configured via the configure script WILL __''NOT''__ WORK outside of Cygwin, if they will build at all.'''
+
+Now that everything is compiled, we can get to the real work of developing your first plugin, but first a point to be well aware of.  ''ALL'' C plugins must define `PURPLE_PLUGINS` by using the `#define` preprocessor directive.  This definition ''must'' occur before including any libpurple, Pidgin, or Finch header files.  Failure to have `#define PURPLE_PLUGINS` in your source file leads to very strange errors that are difficult to diagnose.  Just don't forget to do it!
+
+== Hello, World! ==
+Every programming language's tutorial has its own Hello, World! first application.  Why should our plugin tutorial be any different?  Let's dig in.  First, go to `~/development/pidgin-2.0.2/libpurple/plugins` and create the file helloworld.c with your favorite editor.  The contents of the file will be this:
+ {{{
+#!c
+#define PURPLE_PLUGINS
+
+#include <glib.h>
+
+#include "notify.h"
+#include "plugin.h"
+#include "version.h"
+
+static gboolean
+plugin_load(PurplePlugin *plugin) {
+    purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
+                        "This is the Hello World! plugin :)", NULL, NULL, NULL);
+
+    return TRUE;
+}
+
+static PurplePluginInfo info = {
+    PURPLE_PLUGIN_MAGIC,
+    PURPLE_MAJOR_VERSION,
+    PURPLE_MINOR_VERSION,
+    PURPLE_PLUGIN_STANDARD,
+    NULL,
+    0,
+    NULL,
+    PURPLE_PRIORITY_DEFAULT,
+
+    "core-hello_world",
+    "Hello World!",
+    "1.1",
+
+    "Hello World Plugin",          
+    "Hello World Plugin",          
+    NULL,                          
+    "http://helloworld.tld",     
+    
+    plugin_load,                   
+    NULL,                          
+    NULL,                          
+                                   
+    NULL,                          
+    NULL,                          
+    NULL,                        
+    NULL,                   
+    NULL,                          
+    NULL,                          
+    NULL,                          
+    NULL                           
+};                               
+    
+static void                        
+init_plugin(PurplePlugin *plugin)
+{                                  
+}
+
+PURPLE_INIT_PLUGIN(hello_world, init_plugin, info)
+ }}}
+
+So, what does all this mean?  Well, let's go through this with a line by line analysis.  The `#define PURPLE_PLUGINS` is required, as we mentioned above.
+
+Next, we include glib.h, the header for !GLib.  We do this mainly for the `gboolean` typedef and the other !GLib wrappers for the standard C types.  After this, we include `notify.h`, `plugin.h`, and `version.h`.  The `plugin.h` header includes definitions that all plugins need, such as the type `PurplePluginInfo` and the macros `PURPLE_PLUGIN_MAGIC` and `PURPLE_INIT_PLUGIN()`.
+
+The `version.h` header defines `PURPLE_MAJOR_VERSION` and `PURPLE_MINOR_VERSION`.  There's not much that you need to know about anything in `version.h`, except that they are required and will prevent your plugin from crashing Pidgin if it's probed by an older or newer Pidgin, such as 1.5.1 or 3.0.0 (which of course does not yet exist at the time of this writing), where things are different and your plugin doesn't know about the differences.
+
+The `notify.h` header defines a bunch of notification functions.  For the scope of this part of the tutorial, it's not important to know anything about the contents of the file.  We'll use it for one function call to prove that our plugin works.  Later sections of the tutorial will come back to the notify API and flesh it out a bit more for readers.
+
+Moving on, the `plugin_load` function is defined.  This is not a required function to implement, but if you choose to implement it, libpurple will call the function when the plugin is loaded.  You can use it to initialize any global variables in your source file, to connect to signals, and so on.  Here, we'll use it just to display a message by calling a function from `notify.h`.
+
+Next in our source file we have the declaration and initialization of a global variable.  We called this variable info, and it is of the type `PurplePluginInfo`.  Every plugin is required to declare and initialize a variable of this type in order to tell libpurple about the plugin.  This next code snippet is the exact same struct declaration and initialization from the snippet above, but with some comments included to explain the function of each member of the struct.
+ {{{
+#!c
+static PurplePluginInfo info = {
+    PURPLE_PLUGIN_MAGIC,    /* Plugin magic, this must always be
+                               PURPLE_PLUGIN_MAGIC.*/
+
+    PURPLE_MAJOR_VERSION,   /* This is also defined in libpurple.  It helps
+                               libpurple's plugin system determine which version
+                               of libpurple this plugin was compiled for, and
+                               whether loading it will cause problems. */
+
+    PURPLE_MINOR_VERSION,   /* See previous */
+
+    PURPLE_PLUGIN_STANDARD, /* PurplePluginType: There are 4 different values for
+                               this field.  The first is PURPLE_PLUGIN_UNKNOWN,
+                               which should not be used.  The second is
+                               PURPLE_PLUGIN_STANDARD; this is the value most
+                               plugins will use. Next, we have PURPLE_PLUGIN_LOADER;
+                               this is the type you want to use if your plugin will
+                               make it possible to load non-native plugins.  For
+                               example, the Perl and Tcl loader plugins are of this
+                               type.  Last, we have PURPLE_PLUGIN_PROTOCOL.  If your
+                               plugin is going to allow the user to connect to
+                               another network, this is the type you'd want to use. */
+
+    NULL,                   /* This field is the UI requirement.  If you're writing
+                               a core plugin, this must be NULL and the plugin must
+                               not contain any UI code.  If you're writing a Pidgin
+                               plugin, you need to use PIDGIN_PLUGIN_TYPE.  If you
+                               are writing a Finch plugin, you would use
+                               FINCH_PLUGIN_TYPE.*/
+
+    0,                      /* This field is for plugin flags.  Currently, the only
+                               flag available to plugins is invisible
+                               (PURPLE_PLUGIN_FLAG_INVISIBLE). It causes the plugin
+                               NOT to appear in the list of plugins. */
+
+    NULL,                   /* This is a GList of plugin dependencies.  In other words,
+                               it's a GList of plugin id's that your plugin depends on.
+                               Set this value to NULL no matter what.  If your plugin
+                               has dependencies, set them at run-time in the
+                               plugin_init function. */
+
+    PURPLE_PRIORITY_DEFAULT,/* This is the priority libpurple with give your plugin.
+                               There are three possible values for this field,
+                               PURPLE_PRIORITY_DEFAULT, PURPLE_PRIORITY_HIGHEST, and
+                               PURPLE_PRIORITY_LOWEST. */
+
+    "core-hello_world",     /* This is your plugin's id.  There is a whole page dedicated
+                               to this in the Related Pages section of the API docs. */
+
+    "Hello World!",         /* This is your plugin's name.  This is what will be
+                               displayed for your plugin in the UI. */
+
+    "1.1",                  /* This is the version of your plugin. */
+
+    "Hello World Plugin",   /* This is the summary of your plugin.  It should be a short
+                               blurb.  The UI determines where, if at all, to display
+                               this. */
+
+    "Hello World Plugin",   /* This is the description of your plugin. It can be as long
+                               and as descriptive as you like.  And like the summary,
+                               it's up to the UI where, if at all, to display this (and
+                               how much to display). */
+
+    "My Name <email@helloworld.tld">, /* This is where you can put your name and e-mail
+                                         address. */
+
+    "http://helloworld.tld",/* This is the website for the plugin.  This tells users
+                               where to find new versions, report bugs, etc. */
+
+    plugin_load,            /* This is a pointer to a function for libpurple to call when
+                               it is loading the plugin.  It should be of the type:
+
+                                  gboolean plugin_load(PurplePlugin *plugin)
+
+                               Returning FALSE will stop the loading of the plugin.
+                               Anything else would evaluate as TRUE and the plugin will
+                               continue to load. */
+
+    NULL,                   /* Same as above except it is called when libpurple tries to
+                               unload your plugin.  It should be of the type:
+
+                                  gboolean plugin_unload(PurplePlugin *plugin)
+
+                               Returning TRUE will tell libpurple to continue unloading
+                               while FALSE will stop the unloading of your plugin. */
+
+    NULL,                   /* Similar to the two above members, except this is called
+                               when libpurple tries to destory the plugin.  This is
+                               generally only called when for some reason or another the
+                               plugin fails to probe correctly.  It should be of the type:
+
+                                  void plugin_destroy(PurplePlugin *plugin) */
+
+    NULL,                   /* This is a pointer to a UI-specific struct.  For a Pidgin
+                               plugin it will be a pointer to a PidginPluginUiInfo
+                               struct, for example. */
+
+    NULL,                   /* This is a pointer to either a PurplePluginLoaderInfo
+                               struct or a PurplePluginProtocolInfo struct, and is
+                               beyond the scope of this document. */
+
+    NULL,                   /* This is a pointer to a PurplePluginUiInfo struct.  It is
+                               a core/ui split way for core plugins to have a UI
+                               configuration frame.  You can find an example of this
+                               code in libpurple/plugins/pluginpref_example.c */
+
+    NULL,                   /* This is a function pointer where you can define "plugin
+                               actions".  The UI controls how they're displayed.  It
+                               should be of the type:
+
+                                  GList *function_name(PurplePlugin *plugin,
+                                                       gpointer context)
+
+                               It must return a GList of PurplePluginActions. */
+
+    NULL,                   /* This is a pointer reserved for future use.  We set it to
+                               NULL to indicate we don't need it. */
+
+    NULL,                   /* This is a pointer reserved for future use.  We set it to
+                               NULL to indicate we don't need it. */
+
+    NULL,                   /* This is a pointer reserved for future use.  We set it to
+                               NULL to indicate we don't need it. */
+
+    NULL                    /* This is a pointer reserved for future use.  We set it to
+                               NULL to indicate we don't need it. */
+};
+ }}}
+
+Finally in our source file, we have the `init_plugin` function and the call to the macro `PURPLE_INIT_PLUGIN`.  The `init_plugin` function is called whenever libpurple probes the plugin.  Most plugins will add their prefs to the prefs tree here (more on prefs in another section of the tutorials), as well as do the necessary initialization for translation support (more on that in other documentation).
+
+Every plugin '''''MUST''''' call the `PURPLE_INIT_PLUGIN` macro.  The call to this macro tells libpurple some very basic things about your plugin, like what name to use if someone compiles your plugin statically into a binary, which function is the `init_plugin` function (because you can call it anything!), and the name of the `PurplePluginInfo` structure (which also can be called by any name you want).  Libpurple reads this information when probing the plugin.  If this call is missing, the plugin will not successfully probe and cannot ever load.
+
+== Compile, Install, and Load the Hello, World! Plugin ==
+Now that we have a complete plugin source file, we need to compile it.  From `~/development/pidgin-2.0.2/libpurple/plugins`, run `make helloworld.so` (if using Windows, `make -f Makefile.mingw helloworld.dll`).  If you copied and pasted the code correctly, this should compile without incident.  You can move the resulting .so file to ~/.purple/plugins (move the resulting .dll file to `%APPDATA%\.purple\plugins` on Windows).  Now when you open the Plugins dialog in Pidgin or Finch, the plugin should show up.  When you load it you should see a message pop up.