# HG changeset patch # User Eric Warmenhoven # Date 965768117 0 # Node ID 9a01b3fb1a9da4a891b503a5ddca074082b63f10 # Parent 525c566741daf8c93e589aefa839b07291517fb4 [gaim-migrate @ 649] added a file to help people try to hack gaim committer: Tailor Script diff -r 525c566741da -r 9a01b3fb1a9d HACKING --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/HACKING Tue Aug 08 20:55:17 2000 +0000 @@ -0,0 +1,228 @@ +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, 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 files. Hopefully +that's enough to get most of you going. + +There's one little thing that's just a pet peeve, and it's really stupid. +In ./configure there's and --enable-debug option. This does two things: +compiles with -Wall, and prints debugging information to stdout. The +debugging information is printed to the debug window (which can be turned +on in the preferences) whether or not --enable-debug was selected. Most +of the information that's printed is useless anyway though; so the +--enable-debug option really doesn't do a whole lot. + + +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). It +then draws the login window by calling show_login, and waits for input. + +At the login window, when "signon" is clicked, dologin() is called. This +in turn calls serv_login, which checks to see if you want to use Oscar or +TOC, and calls oscar_login or toc_login appropriately. We'll assume TOC +for the rest of this discussion; Oscar has a lot of bad hacks to get it +working that I don't even want to think about. + +After you're signed in (I'll skip that discussion - I doubt many people +are going to change the login process, since it pretty much just folows +PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and +waits for input from two places: the server and the user. The first place +it gets input from after signon is invariably the server, when the server +tells Gaim which buddies are signed on. + +When there is information ready to be read from the server, toc_callback +is called (by GDK) to parse the incoming information. On an UPDATE, +serv_got_update is called, which takes care of things like notifying +conversation windows of the update if need be; notifying the plugins; +and finally, calling set_buddy. + +set_buddy is one of the most frequently called functions in gaim, one of +the largest functions in gaim, and probably one of the buggiest functions +in gaim. It is responsible for updating the pixmaps in the buddy list; +notifying plugins of various events; updating the tooltips for buddies; +making sounds; and updating the ticker. It's also called once per online +buddy every 20 seconds (by GTK through update_all_buddies). + +When the user opens a new conversation window, new_conversation is called. +That's easy enough. If there isn't a conversation with the person already +open (checked by calling find_conversation), show_conv is called to +create the new window. All sorts of neat things happen there, but it's +mostly drawing the window. show_conv is the best place to edit the UI. Be +prepared for some incredibly bad GTK programming. (Rob's fixing this as +we speak no doubt.) + +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. + +aim.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. Watch out for bad Oscar + sign in hacks. + +away.c: + This takes care of most of the away stuff: setting the away message + (do_im_away); coming back (do_im_back); drawing the away window; + etc. To be honest I haven't looked at this file in months. + +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 not only nearly everything buddy-related (the buddy + list, the permit/deny lists, and the window), but also a lot of the + code flow and util functions. Look for good things like find_buddy, + set_buddy, and signoff() here. + +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 + is created. + +conversation.c: + This is where most of the functions dealing with the IM and chat windows + are hidden. It tries to abstract things as much as possible, but doesn't + do a very good job. This is also where things like "Enter sends" and + "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The + chat and IM toolbar (with the B/I/U/S buttons) are both built from the + same function, build_conv_toolbar. + +dialogs.c: + A massive file with a lot of little utility functions. This is where + all of those little dialog windows are created. Things like the warn + dialog and the add buddy dialog are here. Not all of the dialogs in + gaim are in this file, though. But most of them are. This is also + where do_import is housed, to import buddy lists. + +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. + +gnome_applet_mgr.c: + A hideous creation from the days before I started working on gaim. Most + of it works, but it has functionsLikeThis. I hate looking at this + file, but I'm too lazy to change the functions. The best functions + are things like set_applet_draw_open, whose sole purpose is to set a + global variable to TRUE. + +gtkhtml.c: + This is really just one big hack. It started off as an HTML widget that + was written for Gnome as far as I can tell. The current version is + huge, requires way too many libs, and is too hard to upgrade to. But + we've managed to hack this poor old version into basically what we + need it for. I recommend not looking at this file if you want to save + your sanity. + +gtkticker.c: + Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that + widget. It's cool, and it's tiny. + +html.c: + Don't ask my why this is called html.c. Most of it is just grab_url, + which does like the name says; it downloads a URL to show in the + GtkHTML widget. http.c would be a more appropriate name, but that's OK. + +idle.c: + There is a very good reason why this file is still on version 1.1 + in CVS. The entire thing is #if 0'd out. I haven't ever really taken + a good look at it, but I think what it was supposed to have done is + set you as being away when a screensaver came on. + +network.c: + This has two functions: get_address and connect_address, both of which + call proxy functions. If you want to see how these are used, look at + toc.c and/or rvous.c. These are really just front-ends to the proxy + stuff; use these instead of calling the proxy functions. + +oscar.c: + One big hack of copied code. This is supposed to be the libfaim tie-in + in gaim. Most of it is just copied straight from faimtest, the small + program that comes with libfaim. I'm not even sure how half of it works, + if that makes you feel any better. + +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. + +plugins.c: + This is the "plugin plug", as the file states. This file is probably + the only file in all of gaim that at the top has all of the functions + and global and static variables named out for you. It makes reading + it a little easier, but not by much. A lot of the code in here deals + with the plugin window rather than the plugins themselves. + +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. + +proxy.c: + This is where the bulk of the actual networking code is done. The big + function here is proxy_connect, which will connect through the proxy + setup you've chosen (most of which don't work...) or just regularly. + +rvous.c: + This was originally going to be the stuff for all of the Buddy Icon + and Voice Chat stuff, but I got really sick of protocol hacking really + quick. Now it only houses the file transfer stuff, which only works + for TOC. + +server.c: + This is where all of the differentiation between TOC and Oscar is + done. Nearly everything that's network related goes through here + at one point or another. This has good things like serv_send_im and + serv_got_update. Most of it should be pretty self-explanatory. + +sound.c: + The big important function is play_sound, which plays one of 4 (actually + 6) sounds. One of the sounds is called in 3 different events, which + is why there are actually 6 sounds. This then calls play which then + checks for esd, then nas if that's not available, then falls back + to /dev/audio. + +ticker.c: + Syd is just so cool. I really can't get over it. He let me come + visit him at Netscape one day, and I got to see all of their toys + (don't worry, I'm under an NDA). Anyway, this file is for the buddy + ticker. This is also a damn cool file because it's got all of the + functions that you'd want right up at the top. Someday I want to be + as cool as Syd. + +toc.c: + This handles everything TOC-related, including parsing gaim's buddy + list. Most of this file is toc_callback, which parses the incoming + information from the server. I really don't like TOC though. + +util.c: + There's not really a lot of cohesion to this file; it's just a lot of + stuff that happened to be thrown into it for no apparent reason. None + of it is particularly tasty; it's all just utility functions. Just + like the name says. + + +So that's our little tour of the internals of Gaim. It's really not +difficult to figure out if you've spent any time with GTK. I'm looking +forward to getting all of your patches :) diff -r 525c566741da -r 9a01b3fb1a9d Makefile.am --- a/Makefile.am Tue Aug 08 05:02:59 2000 +0000 +++ b/Makefile.am Tue Aug 08 20:55:17 2000 +0000 @@ -1,6 +1,6 @@ EXTRA_DIST = gaim.spec.in gaim_applet.gnorba gaim.desktop gaim_applet.desktop gaim.soundlist \ - buddytrans buddytrans2 README.plugins + buddytrans buddytrans2 README.plugins HACKING if GNOMEAPPLET