Mercurial > pidgin
comparison doc/ChangeLog @ 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.
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Sat, 16 Dec 2006 04:59:55 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
14190:366be2ce35a7 | 14191:009db0b357b5 |
---|---|
1 version 0.11.0pre5: | |
2 The build process for plugins has changed slightly. Everything still | |
3 works more or less the same from a user point of view, that is, 'make | |
4 file.so' will still turn file.c into a plugin. The build now uses | |
5 libtool in an attempt to increase portability. By using libtool the | |
6 act of compiling and linking has been divided into two steps (to be | |
7 precise it always was two but we only called gcc once; now we call | |
8 libtool twice). PLUGIN_CFLAGS has also been added. Any -D switches you | |
9 were passing in PLUGIN_LIBS should be passed in PLUGIN_CFLAGS now. | |
10 | |
11 version 0.11.0pre1: | |
12 Gaim is now multi-connection based. This represents a significant | |
13 change. Most of the code was modified, though most of the modifications | |
14 were small (referencing an int as part of a struct as opposed to as a | |
15 global int). Plugins need to be modified to match the new function | |
16 declarations and such. | |
17 | |
18 Gaim now uses GModule from the GLib library for plugins. This brings | |
19 a few changes. gaim_plugin_init is now passed a GModule *, which it | |
20 should use for all of its callbacks. gaim_plugin_init now returns | |
21 char * instead of int instead of void. If gaim_plugin_init returns | |
22 NULL then gaim assumes everything was OK and proceeds. Otherwise, it | |
23 displays the error message and unloads your plugin. There is no more | |
24 gaim_plugin_error (at least, that gaim itself will use. You may wish | |
25 to simply return gaim_plugin_error() in gaim_plugin_init). | |
26 | |
27 Because gaim now uses GModule, plugins are opened with RTLD_GLOBAL. I | |
28 had previously wanted to avoid this, but there are simply too many | |
29 benefits gained from using GModule to reject it for this reason. This | |
30 means that plugins can now call each other's functions. Beware, this | |
31 has good and bad implications. If you call a function, it will look | |
32 first in your plugin, and then in gaim's global symbol table, including | |
33 other plugins. | |
34 | |
35 The new system allows for protocol plugins. New protocols (including | |
36 Yahoo, MSN, IRC, ICQ, etc) can be loaded dynamically. However, most | |
37 of these plugins are going to be controlled by the gaim maintainers. | |
38 If you have interest in writing a protocol plugin, please talk to one | |
39 of us before you start. | |
40 | |
41 That's about all that I'm going to talk about. My SN is EWarmenhoven | |
42 if you have any questions (like what the hell struct gaim_connection is | |
43 and what its relation to struct aim_user is). | |
44 | |
45 version 0.10.0: | |
46 Rather than have a separate CFLAGS and LDFLAGS for the plugins than | |
47 for gaim, and doing all kinds of crazy things to work around the | |
48 problems that creates, the plugins now have the same CFLAGS and LIBS. | |
49 The plugins also have PLUGIN_LIBS which can be passed at make time. | |
50 This makes things like #ifdef USE_APPLET and #ifdef USE_PERL much more | |
51 reliable. (#include "config.h" in order to get all the #defines) | |
52 | |
53 The internals of gaim plugin events got modified slightly. It should | |
54 have no effect on existing plugins or the way plugins are made. The | |
55 change was to make my life easier adding perl. It should also make | |
56 adding new plugin events even easier than before (though I doubt that | |
57 any more will ever be added). Also, events are printed to the debug | |
58 window. | |
59 | |
60 event_buddy_away was being triggered every blist_update for every away | |
61 buddy. This got fixed, but now when you sign on, event_buddy_away may | |
62 be called before event_buddy_signon. Not that it should matter much. | |
63 | |
64 Just after I finish saying that no more events will be added, I go and | |
65 add one. Go figure. Anyway, it's event_new_conversation. Enough people | |
66 asked me to add it, and I found it useful enough, that I finally did | |
67 add it. It gets passed a char *, the name of the person who the | |
68 conversation is with. This gets triggered when a new conversation | |
69 window is created, in case you couldn't figure it out on your own. | |
70 | |
71 event_blist_update wasn't being called if you weren't reporting idle | |
72 time or if you were idle. This got fixed. | |
73 | |
74 version 0.9.20: | |
75 It's 3 am the night before finals, it's obviously a good time to hack | |
76 gaim. | |
77 | |
78 This became quite long, and if you don't want to read it all, here's | |
79 the important stuff summed up: | |
80 - 9 new events (see SIGNALS file for more details) | |
81 - int gaim_plugin_init(void *) (no longer returns void, see error.c) | |
82 - void gaim_plugin_unload(void *) (to allow plugin to remove itself) | |
83 - can only load 1 instance of the same plugin | |
84 - PLUGIN_LIBS for extra libraries for plugin | |
85 | |
86 The first thing to note is that there are about 9 new events plugins | |
87 can attach to, most of them dealing with chat, since I know that was a | |
88 big thing that was missing. Please note that I was nice and decided to | |
89 tack these extra events onto the end of the enum, which means that | |
90 plugins do not have to be recompiled in order for them to still work. | |
91 | |
92 The big change is that gaim_plugin_init no longer returns void, but | |
93 int. If it returns 0+, gaim interprets this as there being no error, | |
94 and continues with loading as normal. (This should be backwards- | |
95 compatible: returning 0/1 is the equivalent of returning void.) If it | |
96 returns a number less than 0, there was an error loading detected by | |
97 the plugin. At that point, gaim will try to clean things up by removing | |
98 any callbacks that have been added by the plugin. It will then try to | |
99 call the plugin's gaim_plugin_error function, if there is one. The | |
100 function should take an int (the int returned by gaim_plugin_init) and | |
101 return a char*. If the char* is not NULL, it is displayed by gaim as an | |
102 error message. The plugin is then unloaded and closed and life goes | |
103 back to normal. If any of that was confusing, it was confusing to me, | |
104 too. I added a plugin, error.c, which should help clear things up. | |
105 | |
106 Another big thing to note is that plugins can unload themselves. A good | |
107 example of why this is useful is a ticker plugin. If the user closes | |
108 the ticker window, they obviously want the plugin to be unloaded. Gaim | |
109 has no way of knowing that; therefore, the plugin must tell gaim that | |
110 it is to be unloaded. To have a plugin unload itself, simply call | |
111 gaim_plugin_unload(void *) (the void* is the handle passed to | |
112 gaim_plugin_init). Because you are explicitly asking to be removed, | |
113 gaim assumes that you have done any cleanup already, and so does not | |
114 call gaim_plugin_remove. Rather, it simply removes your callbacks and | |
115 unloads the plugin. (There is some trickery to this. Think about it: | |
116 your plugin calls the function, your plugin is unloaded, and execution | |
117 returns to your plugin, which no longer exists. This would cause a | |
118 segfault if it behaved exactly as described. Instead, the plugin is | |
119 removed from the list of plugins, and removed 5 seconds later. By then | |
120 the plugin should be effectively gone, though still in memory.) | |
121 | |
122 In previous versions of gaim, you could load multiple copies of the | |
123 same plugin. This is no longer the case. The reason for this was that | |
124 there were not two instances of the plugin in memory; rather, one copy | |
125 and two structures representing the same plugin. Then, the callbacks | |
126 would be called twice (since the plugin would most likely act the same | |
127 across multiple instances), and when one was unloaded, all callbacks | |
128 for both instances would be removed. Rather than deal with two copies | |
129 of the same plugin, it is easier and cleaner to only handle one. | |
130 | |
131 Sometimes it's necessary to link a plugin with libraries other than the | |
132 ones needed for GTK. Before, it was necessary to modify the Makefile to | |
133 do so (which was usually messy since it's generated by GNU automake). | |
134 Now, you can simply set the environment variable PLUGIN_LIBS to be the | |
135 extra libraries you want to link in. For example, to link plugin.c with | |
136 the math library, you can run the command | |
137 PLUGIN_LIBS=-lm make plugin.so | |
138 To link with multiple plugins, make sure to indicate spaces, e.g. | |
139 PLUGIN_LIBS='-lm -lcrypt' make encrypt.so | |
140 | |
141 There is a new event, event_quit, which signifies that gaim has exited | |
142 correctly (i.e. didn't segfault). Also, after this event is called, all | |
143 plugins are removed, and their gaim_plugin_remove function is called. | |
144 This behavior is different from previous versions; however, it is the | |
145 proper way of doing things, and should have no effect on current | |
146 plugins. The reason event_quit exists despite plugins being removed at | |
147 quit is because a plugin can be removed without gaim quitting. They are | |
148 distinctly separate events. | |
149 | |
150 The new events mean that some versions of gaim have certain events, | |
151 others don't. The thing I find fascinating though is that even if a | |
152 plugin is compiled for a later version, it will still be backwards- | |
153 compatible, even if it makes use of the newer events. The reason why | |
154 is the names of the events are stored as integers, and those integers | |
155 will never match an event in a prior version. This means you don't | |
156 have to worry about which version the person is using, only which | |
157 version the person is compiling against. For simplicity's sake, please | |
158 assume people are compiling against the latest version. For | |
159 practicality's sake, VERSION is #define'd to be the version you're | |
160 compiling against, starting with 0.9.20. Prior versions do not have | |
161 this defined in the standard plugin Makefile. |