comparison HACKING @ 6797:053b577e08f2

[gaim-migrate @ 7337] Okay, our text files are REALLY OLD. they need massively updated, HACKING especially is like 2/3rds wrong. but there is more wrong than i care to deal with right now. over the next few days you will hopefully see some updates, BUT IT WON'T BE ENOUGH. someone had better decide to help out :-) committer: Tailor Script <[e-mail]>

6796:f5f2669970a0

A lot of people have tried to hack gaim, but haven't been able to because
the code is just so horrid. Well, the code isn't getting better anytime
soon (I hate GNU indent), so to help all you would-be hackers help out
gaim, here's a brief tutorial on how gaim works. I'll quickly describe
the logical flow of things, then what you'll find in each of the source

two trees, or even two copies of the same file). Then when you're ready to
make your patch, simply run 'cvs diff -u >my.patch' and send it off;
either post it on sf.net/projects/gaim in the patches section, or email it
to [e-mail].

This file was last modified by $Author: lschiere $ on
$Date: 2003-02-18 09:36:15 -0500 (Tue, 18 Feb 2003) $. Do not expect any information contained
within to be current or correct.

Here's something new. Someone requested that I comment the code. No. I'm a
lazy bastard, and I understand most of the code, so I don't need the
comments. I understand that some of you do though. So give me the names of
specific functions that you'd like commented and I'll see what I can do.
It's more likely that those comments will be updated with the code than
this file is, though even that is still unlikely.


CODING STYLE
============

Coding styles are like assholes, everyone has one and no one likes anyone

NO goto. I'm very likely to refuse a patch if it makes use of goto. If you
feel the need to use goto, you need to rethink your design and flow.


PROGRAM FLOW
============

Before gaim does anything you can see, it initializes itself, which is
mostly just reading .gaimrc (handled by the functions in gaimrc.c) and
parsing command-line options. It then draws the login window by calling
show_login, and waits for input.

At the login window, when "Accounts" is clicked, account_editor() is
called. This then displays all of the users and various information
about them. (Don't ask about what happens when "Sign On" is called. It's
quite hackish. The only reason the login window is there anymore is to

That's pretty much it for the quick tutorial. I know it wasn't much but
it's enough to get you started. Make sure you know GTK before you get too
involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.


SOURCE FILES
============

about.c:
  Not much to say here, just a few basic functions.

browser.c:
  Code for opening a browser window. Most of the code is trying to deal
  with Netscape. The most important function here is open_url. Have fun.

buddy.c:
  This takes care of the buddy list window and most things related to it.
  It still has some functions that manage the list, but not many.

buddy_chat.c:
  This takes care of the buddy chat stuff. This used to be a lot bigger
  until the chat and IM windows got merged in the code. Now it mostly
  just takes care of chat-specific stuff, like ignoring people and
  keeping track of who's in the room. This is also where the chat window

gaimrc.c:
  This controls everything about the .gaimrc file. There's not really much
  to say about it; this is probably one of the better designed and easier
  to follow files in gaim. The important functions are towards the bottom.

gtkimhtml.c:
  This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
  was different than GNOME's GtkHTML). It's self-contained (it doesn't
  use any of gaim's code) and is actually a separate project from gaim

idle.c:
  This file used to be entirely #if 0'd out of existance. However, thanks
  to some very generous people who submitted patches, this takes care of
  reporting idle time (imagine that). It's a pretty straight-forward file.
  This also takes care of the auto-away stuff.

list.c:
  This file contains all of the routines for managing buddy lists,
  including importing them from a file, saving them, adding and removing
  buddies and groups, etc.

main.c:
  This is where the main() function is. It takes care of a lot of the
  initialization stuff, and showing the login window. It's pretty tiny
  and there's not really much to edit in it. This has some of the most

  with multiple connections. The best function in here by far is the
  account_editor(). auto_login() is also in here (I'm just reading multi.h
  now...). account_editor is really the only function that the UI needs
  to be concerned with.

perl.c:
  This was basically copied straight from X-Chat through the power of
  the GPL.  Perl is the biggest, most confusing piece of C code I've ever
  seen in my life (and keep in mind I'm a gaim hacker). I have a basic
  idea of what's going on in it, but I couldn't tell you exactly. The
  top half sets up perl and tells it what's going on and the bottom half
  implements the AIM module.

prefs.c:
  The important function in here is build_prefs, but the most useful
  function is gaim_button. build_prefs draws the window, and calls
  gaim_button probably 30 or 40 times. (I don't really wanna run grep
  | wc to count.) This is where you add the toggle button for gaim
  preferences. It's very simple, and if you look at a couple of the
  calls to gaim_button you'll figure it out right away. The new prefs
  window uses a CList instead of a Notebook, and there's a pretty bad
  hack to get it to work. I won't tell you what though.

proxy.c:
  Adam (of libfaim glory) got bored one day and rewrote this file, so
  now everything actually works. The main function is proxy_connect,
  which figures out which proxy you want to use (if you want to use one
  at all) and passes off the data to the appropriate function. This file
  should be pretty straight-forward.

prpl.c:
  This file is what lets gaim dynamically load protocols, sort of. All
  of the actual dlopen(), dlsym() stuff is in module.c. But this contains
  all of the functions that the protocol plugin needs to call, and manages

For the PRPLs, the only protocol whose "main" gaim file isn't the same as
the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is
deprecated and you should be using Oscar for ICQ anyway.

HOW BUDDY LISTS WORK
====================

The buddy list is a pain in the ass. Let me start off by saying that. The
most difficult part about getting gaim to do multiple connections was
the buddy list. In its current state it's very much like the UI for
0.10.x and earlier, which is what I was aiming for. However, the code
is completely different. And not much better.

There are two parts to the buddy list: the lists for the connections and
the Buddy List window. list.c contains code to manage the lists themselves
and buddy.c contains the code for the Buddy List window.

Each buddy needs to belong to a connection, it cannot belong to a
"protocol" like in EveryBuddy. The reason is because when you are adding
buddies, you tell the server who is on your buddy list so it can tell you
about them; in order to tell the server, it needs to go out over a
connection. Going out over all connections would not be good, so you need
to specify which connection they go out on.

Managing lists is therefore fairly easy, each group and buddy has an
associated connection. Management functions like add_buddy/remove_buddy
and add_group/remove_group all take a gaim_connection. These are all in
list.c. They're boring.

The window is a lot more fun. There's really only one function that
does anything interesting, and that's set_buddy. (There's also things
like build_edit_tree, but that's boring.) set_buddy is called by
serv_got_update (and should only be called by that function) any time
a user signs on, signs off, goes away, comes back, goes idle, etc, etc,
etc. Various things happen depending on the new state of the buddy.

struct buddy has a member, present, which is set to either 0, 1, or
2. You can check if the buddy is online with "if (b->present)". This
becomes important. present is set to either 0 or 1 by serv_got_update,
or is not set at all. When the buddy is passed to set_buddy, if present
is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2,
to indicate it has already received notification of arrival. It then
does other signin-related stuff: setting the pixmap to the login icon;
updating the conversation windows; etc.

The most important thing it does though, if a buddy is present, is it
checks for the existance of the appropriate group_show and buddy_show for
that buddy.  Each buddy must belong to a group. group_shows are based on
name; there can only be one group_show for each group name. buddy_shows
are based both on name and on group_show; there can only be one buddy_show
in a group_show for each name. However, there can be two buddy_shows
with the same name as long as they have different group_shows.

Each buddy_show has a GList of connections that has registered its related
buddy as being online. set_buddy makes sure that the connection that it's
being passed is part of the connlist for the buddy_show associated with
the struct buddy that it's passed (it helps to know your data structures).

If a buddy logs off (b->present == 0), and a buddy_show exists for
that buddy, then set_buddy will play the logoff sound, change the icon,
remove the connection from the connlist for the buddy_show, etc.

And that's how that works. For the buddy lists, connections own buddies;
for the window, the buddies own the connections. When the buddy_show
connlist count drops to zero it disappears from existance.


PLUGINS
=======

OK, so you want to load a plugin. You go through whatever UI (you
can read all about the UI in plugins.c or whereever). You finally get
to load_plugin, the meat of the plugins stuff (plugins can actually

6797:053b577e08f2

The majority of the below was written by Eric Warmenhoven way back in 
antiquity. I have taken the liberty of attempting to PARTIALLY update
it. I still think its helpful, but use it at your own risk. 
--Luke


A lot of people have tried to hack gaim, but haven't been able to because
the code is just so horrid. Well, the code isn't getting better anytime
soon (I hate GNU indent), so to help all you would-be hackers help out
gaim, here's a brief tutorial on how gaim works. I'll quickly describe
the logical flow of things, then what you'll find in each of the source

two trees, or even two copies of the same file). Then when you're ready to
make your patch, simply run 'cvs diff -u >my.patch' and send it off;
either post it on sf.net/projects/gaim in the patches section, or email it
to [e-mail].

Some Documentation is available on the Gaim api if you run the command 
$make docs
after running ./configure (or ./autogen.sh). You will need doxygen and
graphiz dot to generate these docs. 

CODING STYLE
============

Coding styles are like assholes, everyone has one and no one likes anyone

NO goto. I'm very likely to refuse a patch if it makes use of goto. If you
feel the need to use goto, you need to rethink your design and flow.


PROGRAM FLOW  (just about every function name from here on down is wrong.
============   but many of the ideas still apply under different names.)

Before gaim does anything you can see, it initializes itself, which is
mostly just reading ~/.gaim/*.xml (handled by the functions in prefs.[ch])
and parsing command-line options. It then draws the login window by 
calling show_login, and waits for input.

At the login window, when "Accounts" is clicked, account_editor() is
called. This then displays all of the users and various information
about them. (Don't ask about what happens when "Sign On" is called. It's
quite hackish. The only reason the login window is there anymore is to

That's pretty much it for the quick tutorial. I know it wasn't much but
it's enough to get you started. Make sure you know GTK before you get too
involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.


SOURCE FILES  (this should probly be utterly removed)
============

about.c:
  Not much to say here, just a few basic functions.

browser.c:
  Code for opening a browser window. Most of the code is trying to deal
  with Netscape. The most important function here is open_url. Have fun.

blist.c:
	This takes care of the buddy list backend, the blist.xml file,
	importing old buddy list files, and related things like
	finding buddies and groups.
	
buddy_chat.c:
  This takes care of the buddy chat stuff. This used to be a lot bigger
  until the chat and IM windows got merged in the code. Now it mostly
  just takes care of chat-specific stuff, like ignoring people and
  keeping track of who's in the room. This is also where the chat window

gaimrc.c:
  This controls everything about the .gaimrc file. There's not really much
  to say about it; this is probably one of the better designed and easier
  to follow files in gaim. The important functions are towards the bottom.
  	This file is also utterly deprecated. It is used only for importing
	on upgrade. the prefs.c and prefs.h files replace the control,
	and gtkprefs.c replaces the gui component.

gtkimhtml.c:
  This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
  was different than GNOME's GtkHTML). It's self-contained (it doesn't
  use any of gaim's code) and is actually a separate project from gaim

idle.c:
  This file used to be entirely #if 0'd out of existance. However, thanks
  to some very generous people who submitted patches, this takes care of
  reporting idle time (imagine that). It's a pretty straight-forward file.
  This also takes care of the auto-away stuff.

main.c:
  This is where the main() function is. It takes care of a lot of the
  initialization stuff, and showing the login window. It's pretty tiny
  and there's not really much to edit in it. This has some of the most

  with multiple connections. The best function in here by far is the
  account_editor(). auto_login() is also in here (I'm just reading multi.h
  now...). account_editor is really the only function that the UI needs
  to be concerned with.

prefs.c:
	Read the documentation on this file. This handles the backend
	side of prefs. 

proxy.c:
  Adam (of libfaim glory) got bored one day and rewrote this file, so
  now everything actually works. The main function is proxy_connect,
  which figures out which proxy you want to use (if you want to use one
  at all) and passes off the data to the appropriate function. This file
  should be pretty straight-forward.	
  	Except I STRONGLY suspect that time has broken this file.

prpl.c:
  This file is what lets gaim dynamically load protocols, sort of. All
  of the actual dlopen(), dlsym() stuff is in module.c. But this contains
  all of the functions that the protocol plugin needs to call, and manages

For the PRPLs, the only protocol whose "main" gaim file isn't the same as
the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is
deprecated and you should be using Oscar for ICQ anyway.

PLUGINS (read the plugins howto, this is really out of date)
=======

OK, so you want to load a plugin. You go through whatever UI (you
can read all about the UI in plugins.c or whereever). You finally get
to load_plugin, the meat of the plugins stuff (plugins can actually