# HG changeset patch # User Mark Doliner # Date 1157918753 0 # Node ID 7be98514555e0abfa3945ad6925a4f297404182e # Parent 1a79eb31c2f72e64e845814963450e2ccb475a64 [gaim-migrate @ 17223] Move doc/HOWTO to PLUGINS_HOWTO. Someone should add a section to the bottom of our C Plugin HOWTO that describes how to compile a C plugin outside of the Gaim source tree, and give a really small example Makefile committer: Tailor Script diff -r 1a79eb31c2f7 -r 7be98514555e PLUGINS_HOWTO --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/PLUGINS_HOWTO Sun Sep 10 20:05:53 2006 +0000 @@ -0,0 +1,20 @@ +For information on writing a plugin for Gaim, go +http://gaim.sourceforge.net/api/ and see the HOWTOs in the +"Related Pages" section. + +You can also generate this documentation locally by installing +doxygen and graphviz dot, then running "make docs" in the Gaim +source tree. The documentation will be in the docs/html directory. + +This next paragraph is old and possibly out of date: +Compilation of the plugins is fairly straight-forward; there is a +Makefile in this directory that has a rule for making the .so file +from a .c file. No modification of the Makefile should be necessary, +unless if you simply want to type 'make' to have it made; otherwise, +'make filename.so' will take filename.c and make the .so plugin from +it. If you need to link in with extra libraries, you can set the +environment variable PLUGIN_LIBS to be the libraries you want to link +with. + +It should be possible to compile plugins outside of the Gaim source +tree, which is a much cleaner solution. diff -r 1a79eb31c2f7 -r 7be98514555e doc/HOWTO --- a/doc/HOWTO Sun Sep 10 20:04:20 2006 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,83 +0,0 @@ -Everything in this file should be considered old and potentially out of -date. For more reliable information, install doxygen and graphiz dot, -then run -make docs -in the gaim source tree. This will produce html docs in gaim/docs/html -that will provide an api reference and in the related pages section, -information on perl and c plugins. - - -Ok, this howto is going to be really short and sweet and to the point. - -First off, before you do anything else, in all of the files for your plugin, -put the lines - -#define GAIM_PLUGINS -#include "gaim.h" - -I mean this. Without this, all kinds of things will not work correctly. If you -really want to know exactly what this does, read ../src/gaim.h and learn. But -if you don't want to do that, just know that it's important. - -Now that you've put that there, make sure gaim.h is in your include path. - -Ok, now you're ready to write the plugin. - -The only function that is required is gaim_plugin_init(GModule *). This gets -called as soon as it gets loaded (sort of - man dlopen for more details). If -your function never returns, it will crash gaim! If your plugin uses up all -the memory in the system, it will crash gaim! Once your plugin gets loaded, -it effectively becomes a part of gaim, and anything that goes wrong will look -like it is a problem with gaim itself. I write bugfree code! :) Therefore, it -is your problem, not mine. (I'm usually nice and willing to help you with your -problems though.) - -The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. -DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's -needed for connecting to signals and things. It's a good idea to remember it -somehow. - -gaim_plugin_init should return a char*. If the char* returned is not NULL, it -is interpreted as an error, and used as an error message. See the ChangeLog -file in this directory for more details. - -You can basically do anything you want in the plugin. You can make function -calls, change public widgets, display new widgets, things like that. But the -really neat thing is you can do things at events. For example, when one of -your buddies signs on, you can instantly send them a message. You can modify -the incoming and outgoing text. You can do all kinds of crazy things. Whatever -you want. Check out SIGNALS for more information. - -Plugins can share globals with gaim, but will not share with other plugins. -This is so if you have a global variable GtkWidget *window in your plugin and -J. Random Hacker also has the same name on a global variable, you won't be -constantly overwriting each others' variables. Unfortunately, this also means -that plugins will have difficulty working together. But then again, that's -what shared memory is for. - -Plugins can be configured. This makes it so they don't have to be recompiled -in order to change things internal to them, and it's also just a cool feature -to have :). It's optional; to allow your plugin to be configured, add a -function called gaim_plugin_config(). The advised course of action is to have -it pop up a dialog window; but it's your plugin. - -When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It -doesn't have to be there, but it's nice if, say, you create a window, and when -the plugin gets unloaded, it removes the window. Also, all the callbacks you -have attached to gaim signals will be removed. - -Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) -(the GModule* is the handle passed to gaim_plugin_init). When your plugin gets -unloaded, gaim will remove all of your callbacks. It will not call your -gaim_plugin_remove function, however, since it will assume you have already -done the necessary cleanup. - -Compilation of the plugins is fairly straight-forward; there is a Makefile in -this directory that has a rule for making the .so file from a .c file. No -modification of the Makefile should be necessary, unless if you simply want -to type 'make' to have it made; otherwise, 'make filename.so' will take -filename.c and make the .so plugin from it. If you need to link in with extra -libraries, you can set the environment variable PLUGIN_LIBS to be the libraries -you want to link with. - -There are a few examples in this directory. Enjoy.