| blob | a2ddb6a2eeebfd14f8516890520d9648ff15f9a6 |
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.
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.
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).
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.
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.
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).
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)
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.
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.
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.
71 event_blist_update wasn't being called if you weren't reporting idle
72 time or if you were idle. This got fixed.
74 version 0.9.20:
75 It's 3 am the night before finals, it's obviously a good time to hack
76 gaim.
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
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.
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.
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.)
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.
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
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.
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.