changeset 14504:7be98514555e

[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 <[e-mail]>

--- /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.

--- 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.