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

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/ChangeLog	Sat Dec 16 04:59:55 2006 +0000
@@ -0,0 +1,161 @@
+version 0.11.0pre5:
+	The build process for plugins has changed slightly. Everything still
+	works more or less the same from a user point of view, that is, 'make
+	file.so' will still turn file.c into a plugin. The build now uses
+	libtool in an attempt to increase portability. By using libtool the
+	act of compiling and linking has been divided into two steps (to be
+	precise it always was two but we only called gcc once; now we call
+	libtool twice). PLUGIN_CFLAGS has also been added. Any -D switches you
+	were passing in PLUGIN_LIBS should be passed in PLUGIN_CFLAGS now.
+
+version 0.11.0pre1:
+	Gaim is now multi-connection based. This represents a significant
+	change. Most of the code was modified, though most of the modifications
+	were small (referencing an int as part of a struct as opposed to as a
+	global int). Plugins need to be modified to match the new function
+	declarations and such.
+
+	Gaim now uses GModule from the GLib library for plugins. This brings
+	a few changes. gaim_plugin_init is now passed a GModule *, which it
+	should use for all of its callbacks. gaim_plugin_init now returns
+	char * instead of int instead of void. If gaim_plugin_init returns
+	NULL then gaim assumes everything was OK and proceeds. Otherwise, it
+	displays the error message and unloads your plugin. There is no more
+	gaim_plugin_error (at least, that gaim itself will use. You may wish
+	to simply return gaim_plugin_error() in gaim_plugin_init).
+
+	Because gaim now uses GModule, plugins are opened with RTLD_GLOBAL. I
+	had previously wanted to avoid this, but there are simply too many
+	benefits gained from using GModule to reject it for this reason. This
+	means that plugins can now call each other's functions. Beware, this
+	has good and bad implications. If you call a function, it will look
+	first in your plugin, and then in gaim's global symbol table, including
+	other plugins.
+
+	The new system allows for protocol plugins. New protocols (including
+	Yahoo, MSN, IRC, ICQ, etc) can be loaded dynamically. However, most
+	of these plugins are going to be controlled by the gaim maintainers.
+	If you have interest in writing a protocol plugin, please talk to one
+	of us before you start.
+
+	That's about all that I'm going to talk about. My SN is EWarmenhoven
+	if you have any questions (like what the hell struct gaim_connection is
+	and what its relation to struct aim_user is).
+
+version 0.10.0:
+	Rather than have a separate CFLAGS and LDFLAGS for the plugins than
+	for gaim, and doing all kinds of crazy things to work around the
+	problems that creates, the plugins now have the same CFLAGS and LIBS.
+	The plugins also have PLUGIN_LIBS which can be passed at make time.
+	This makes things like #ifdef USE_APPLET and #ifdef USE_PERL much more
+	reliable. (#include "config.h" in order to get all the #defines)
+
+	The internals of gaim plugin events got modified slightly. It should
+	have no effect on existing plugins or the way plugins are made. The
+	change was to make my life easier adding perl. It should also make
+	adding new plugin events even easier than before (though I doubt that
+	any more will ever be added). Also, events are printed to the debug
+	window.
+
+	event_buddy_away was being triggered every blist_update for every away
+	buddy. This got fixed, but now when you sign on, event_buddy_away may
+	be called before event_buddy_signon. Not that it should matter much.
+
+	Just after I finish saying that no more events will be added, I go and
+	add one. Go figure. Anyway, it's event_new_conversation. Enough people
+	asked me to add it, and I found it useful enough, that I finally did
+	add it. It gets passed a char *, the name of the person who the
+	conversation is with. This gets triggered when a new conversation
+	window is created, in case you couldn't figure it out on your own.
+
+	event_blist_update wasn't being called if you weren't reporting idle
+	time or if you were idle. This got fixed.
+
+version 0.9.20:
+	It's 3 am the night before finals, it's obviously a good time to hack
+	gaim.
+
+	This became quite long, and if you don't want to read it all, here's
+	the important stuff summed up:
+	- 9 new events (see SIGNALS file for more details)
+	- int gaim_plugin_init(void *) (no longer returns void, see error.c)
+	- void gaim_plugin_unload(void *) (to allow plugin to remove itself)
+	- can only load 1 instance of the same plugin
+	- PLUGIN_LIBS for extra libraries for plugin
+
+	The first thing to note is that there are about 9 new events plugins
+	can attach to, most of them dealing with chat, since I know that was a
+	big thing that was missing. Please note that I was nice and decided to
+	tack these extra events onto the end of the enum, which means that
+	plugins do not have to be recompiled in order for them to still work.
+
+	The big change is that gaim_plugin_init no longer returns void, but
+	int.  If it returns 0+, gaim interprets this as there being no error,
+	and continues with loading as normal. (This should be backwards-
+	compatible: returning 0/1 is the equivalent of returning void.) If it
+	returns a number less than 0, there was an error loading detected by
+	the plugin. At that point, gaim will try to clean things up by removing
+	any callbacks that have been added by the plugin. It will then try to
+	call the plugin's gaim_plugin_error function, if there is one. The
+	function should take an int (the int returned by gaim_plugin_init) and
+	return a char*. If the char* is not NULL, it is displayed by gaim as an
+	error message.  The plugin is then unloaded and closed and life goes
+	back to normal. If any of that was confusing, it was confusing to me,
+	too. I added a plugin, error.c, which should help clear things up.
+
+	Another big thing to note is that plugins can unload themselves. A good
+	example of why this is useful is a ticker plugin. If the user closes
+	the ticker window, they obviously want the plugin to be unloaded. Gaim
+	has no way of knowing that; therefore, the plugin must tell gaim that
+	it is to be unloaded. To have a plugin unload itself, simply call
+	gaim_plugin_unload(void *) (the void* is the handle passed to
+	gaim_plugin_init). Because you are explicitly asking to be removed,
+	gaim assumes that you have done any cleanup already, and so does not
+	call gaim_plugin_remove. Rather, it simply removes your callbacks and
+	unloads the plugin. (There is some trickery to this. Think about it:
+	your plugin calls the function, your plugin is unloaded, and execution
+	returns to your plugin, which no longer exists. This would cause a
+	segfault if it behaved exactly as described. Instead, the plugin is
+	removed from the list of plugins, and removed 5 seconds later. By then
+	the plugin should be effectively gone, though still in memory.)
+
+	In previous versions of gaim, you could load multiple copies of the
+	same plugin. This is no longer the case. The reason for this was that
+	there were not two instances of the plugin in memory; rather, one copy
+	and two structures representing the same plugin. Then, the callbacks
+	would be called twice (since the plugin would most likely act the same
+	across multiple instances), and when one was unloaded, all callbacks
+	for both instances would be removed. Rather than deal with two copies
+	of the same plugin, it is easier and cleaner to only handle one.
+
+	Sometimes it's necessary to link a plugin with libraries other than the
+	ones needed for GTK. Before, it was necessary to modify the Makefile to
+	do so (which was usually messy since it's generated by GNU automake).
+	Now, you can simply set the environment variable PLUGIN_LIBS to be the
+	extra libraries you want to link in. For example, to link plugin.c with
+	the math library, you can run the command
+	PLUGIN_LIBS=-lm make plugin.so
+	To link with multiple plugins, make sure to indicate spaces, e.g.
+	PLUGIN_LIBS='-lm -lcrypt' make encrypt.so
+
+	There is a new event, event_quit, which signifies that gaim has exited
+	correctly (i.e. didn't segfault). Also, after this event is called, all
+	plugins are removed, and their gaim_plugin_remove function is called.
+	This behavior is different from previous versions; however, it is the
+	proper way of doing things, and should have no effect on current
+	plugins. The reason event_quit exists despite plugins being removed at
+	quit is because a plugin can be removed without gaim quitting. They are
+	distinctly separate events.
+
+	The new events mean that some versions of gaim have certain events,
+	others don't. The thing I find fascinating though is that even if a
+	plugin is compiled for a later version, it will still be backwards-
+	compatible, even if it makes use of the newer events. The reason why
+	is the names of the events are stored as integers, and those integers
+	will never match an event in a prior version. This means you don't
+	have to worry about which version the person is using, only which
+	version the person is compiling against. For simplicity's sake, please
+	assume people are compiling against the latest version. For
+	practicality's sake, VERSION is #define'd to be the version you're
+	compiling against, starting with 0.9.20. Prior versions do not have
+	this defined in the standard plugin Makefile.