diff doc/HOWTO @ 14191:009db0b357b5

This is a hand-crafted commit to migrate across subversion revisions 16854:16861, due to some vagaries of the way the original renames were done. Witness that monotone can do in one revision what svn had to spread across several.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/HOWTO	Sat Dec 16 04:59:55 2006 +0000
@@ -0,0 +1,83 @@
+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.