Mercurial > pidgin.yaz
annotate doc/HOWTO @ 14278:f71894e1700d
[gaim-migrate @ 16963]
Fix a crazy bug that we found at meebo. I'm not sure it
affects gtk Gaim in quite the same way, but what was
happeing is that the conversation sequence number should
be incremented by 1 each time a new conversation is
created (whether created by someone else or created by
you). However, in one place in Gaim conv_seq was being
incremented BEFORE it was used and in another it was
being incremented AFTER it was used. This can lead to
a sequence number being used twice.
committer: Tailor Script <tailor@pidgin.im>
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Mon, 21 Aug 2006 22:50:58 +0000 |
parents | 009db0b357b5 |
children |
rev | line source |
---|---|
14191
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
1 Everything in this file should be considered old and potentially out of |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
2 date. For more reliable information, install doxygen and graphiz dot, |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
3 then run |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
4 make docs |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
5 in the gaim source tree. This will produce html docs in gaim/docs/html |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
6 that will provide an api reference and in the related pages section, |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
7 information on perl and c plugins. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
8 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
9 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
10 Ok, this howto is going to be really short and sweet and to the point. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
11 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
12 First off, before you do anything else, in all of the files for your plugin, |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
13 put the lines |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
14 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
15 #define GAIM_PLUGINS |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
16 #include "gaim.h" |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
17 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
18 I mean this. Without this, all kinds of things will not work correctly. If you |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
19 really want to know exactly what this does, read ../src/gaim.h and learn. But |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
20 if you don't want to do that, just know that it's important. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
21 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
22 Now that you've put that there, make sure gaim.h is in your include path. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
23 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
24 Ok, now you're ready to write the plugin. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
25 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
26 The only function that is required is gaim_plugin_init(GModule *). This gets |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
27 called as soon as it gets loaded (sort of - man dlopen for more details). If |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
28 your function never returns, it will crash gaim! If your plugin uses up all |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
29 the memory in the system, it will crash gaim! Once your plugin gets loaded, |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
30 it effectively becomes a part of gaim, and anything that goes wrong will look |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
31 like it is a problem with gaim itself. I write bugfree code! :) Therefore, it |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
32 is your problem, not mine. (I'm usually nice and willing to help you with your |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
33 problems though.) |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
34 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
35 The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
36 DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
37 needed for connecting to signals and things. It's a good idea to remember it |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
38 somehow. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
39 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
40 gaim_plugin_init should return a char*. If the char* returned is not NULL, it |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
41 is interpreted as an error, and used as an error message. See the ChangeLog |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
42 file in this directory for more details. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
43 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
44 You can basically do anything you want in the plugin. You can make function |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
45 calls, change public widgets, display new widgets, things like that. But the |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
46 really neat thing is you can do things at events. For example, when one of |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
47 your buddies signs on, you can instantly send them a message. You can modify |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
48 the incoming and outgoing text. You can do all kinds of crazy things. Whatever |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
49 you want. Check out SIGNALS for more information. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
50 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
51 Plugins can share globals with gaim, but will not share with other plugins. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
52 This is so if you have a global variable GtkWidget *window in your plugin and |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
53 J. Random Hacker also has the same name on a global variable, you won't be |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
54 constantly overwriting each others' variables. Unfortunately, this also means |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
55 that plugins will have difficulty working together. But then again, that's |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
56 what shared memory is for. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
57 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
58 Plugins can be configured. This makes it so they don't have to be recompiled |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
59 in order to change things internal to them, and it's also just a cool feature |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
60 to have :). It's optional; to allow your plugin to be configured, add a |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
61 function called gaim_plugin_config(). The advised course of action is to have |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
62 it pop up a dialog window; but it's your plugin. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
63 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
64 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
65 doesn't have to be there, but it's nice if, say, you create a window, and when |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
66 the plugin gets unloaded, it removes the window. Also, all the callbacks you |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
67 have attached to gaim signals will be removed. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
68 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
69 Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
70 (the GModule* is the handle passed to gaim_plugin_init). When your plugin gets |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
71 unloaded, gaim will remove all of your callbacks. It will not call your |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
72 gaim_plugin_remove function, however, since it will assume you have already |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
73 done the necessary cleanup. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
74 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
75 Compilation of the plugins is fairly straight-forward; there is a Makefile in |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
76 this directory that has a rule for making the .so file from a .c file. No |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
77 modification of the Makefile should be necessary, unless if you simply want |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
78 to type 'make' to have it made; otherwise, 'make filename.so' will take |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
79 filename.c and make the .so plugin from it. If you need to link in with extra |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
80 libraries, you can set the environment variable PLUGIN_LIBS to be the libraries |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
81 you want to link with. |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
82 |
009db0b357b5
This is a hand-crafted commit to migrate across subversion revisions
Ethan Blanton <elb@pidgin.im>
parents:
diff
changeset
|
83 There are a few examples in this directory. Enjoy. |