Mercurial > pidgin
annotate HACKING @ 958:df664ea5eced
[gaim-migrate @ 968]
This is mostly just a test.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Mon, 09 Oct 2000 09:18:19 +0000 |
parents | b61607d6c2af |
children | fa681641643d |
rev | line source |
---|---|
639 | 1 A lot of people have tried to hack gaim, but haven't been able to because |
2 the code is just so horrid. Well, the code isn't getting better anytime | |
3 soon, so to help all you would-be hackers help out gaim, here's a brief | |
4 tutorial on how gaim works. I'll quickly describe the logical flow of | |
5 things, then what you'll find in each of the source files. Hopefully | |
6 that's enough to get most of you going. | |
7 | |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
8 If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
9 against the absolute latest CVS. I get really annoyed when I get patches |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
10 against the last released version, especially since I don't usually have |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
11 a copy of it on my computer, and gaim tends to change a lot between |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
12 versions. (I sometimes get annoyed when they're against CVS from 3 days |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
13 ago, but can't complain because it's usually my fault that I haven't |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
14 looked at the patch yet.) To get gaim from CVS (if you haven't already), |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
15 run the following commands: |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
16 |
774
b61607d6c2af
[gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
749
diff
changeset
|
17 $ export CVSROOT=:pserver:anonymous@cvs.gaim.sourceforge.net:/cvsroot/gaim |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
18 $ cvs login |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
19 (hit enter as the password) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
20 $ cvs co gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
21 (you'll see it getting all of the files) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
22 $ cd gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
23 $ ./gen |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
24 |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
25 You'll now have your normal gaim tree with ./configure and all. (If you |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
26 want to make your life really simple, learn how CVS works. CVS is your |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
27 friend.) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
28 |
639 | 29 There's one little thing that's just a pet peeve, and it's really stupid. |
706
a9758452f3c4
[gaim-migrate @ 716]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
684
diff
changeset
|
30 In ./configure there's an --enable-debug option. This does two things: |
639 | 31 compiles with -Wall, and prints debugging information to stdout. The |
32 debugging information is printed to the debug window (which can be turned | |
33 on in the preferences) whether or not --enable-debug was selected. Most | |
34 of the information that's printed is useless anyway though; so the | |
35 --enable-debug option really doesn't do a whole lot. | |
36 | |
958
df664ea5eced
[gaim-migrate @ 968]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
774
diff
changeset
|
37 This file was last modified by $Author: warmenhoven $ on $Date: 2000-10-09 05:18:19 -0400 (Mon, 09 Oct 2000) $. |
684
b29c92be568b
[gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
639
diff
changeset
|
38 |
639 | 39 |
40 PROGRAM FLOW | |
41 ============ | |
42 | |
43 Before gaim does anything you can see, it initializes itself, which is | |
44 mostly just reading .gaimrc (handled by the functions in gaimrc.c). It | |
45 then draws the login window by calling show_login, and waits for input. | |
46 | |
47 At the login window, when "signon" is clicked, dologin() is called. This | |
48 in turn calls serv_login, which checks to see if you want to use Oscar or | |
49 TOC, and calls oscar_login or toc_login appropriately. We'll assume TOC | |
50 for the rest of this discussion; Oscar has a lot of bad hacks to get it | |
51 working that I don't even want to think about. | |
52 | |
53 After you're signed in (I'll skip that discussion - I doubt many people | |
706
a9758452f3c4
[gaim-migrate @ 716]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
684
diff
changeset
|
54 are going to change the login process, since it pretty much just follows |
639 | 55 PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and |
56 waits for input from two places: the server and the user. The first place | |
57 it gets input from after signon is invariably the server, when the server | |
58 tells Gaim which buddies are signed on. | |
59 | |
60 When there is information ready to be read from the server, toc_callback | |
61 is called (by GDK) to parse the incoming information. On an UPDATE, | |
62 serv_got_update is called, which takes care of things like notifying | |
63 conversation windows of the update if need be; notifying the plugins; | |
64 and finally, calling set_buddy. | |
65 | |
66 set_buddy is one of the most frequently called functions in gaim, one of | |
67 the largest functions in gaim, and probably one of the buggiest functions | |
68 in gaim. It is responsible for updating the pixmaps in the buddy list; | |
69 notifying plugins of various events; updating the tooltips for buddies; | |
70 making sounds; and updating the ticker. It's also called once per online | |
71 buddy every 20 seconds (by GTK through update_all_buddies). | |
72 | |
73 When the user opens a new conversation window, new_conversation is called. | |
74 That's easy enough. If there isn't a conversation with the person already | |
75 open (checked by calling find_conversation), show_conv is called to | |
76 create the new window. All sorts of neat things happen there, but it's | |
77 mostly drawing the window. show_conv is the best place to edit the UI. Be | |
78 prepared for some incredibly bad GTK programming. (Rob's fixing this as | |
79 we speak no doubt.) | |
80 | |
81 That's pretty much it for the quick tutorial. I know it wasn't much but | |
82 it's enough to get you started. Make sure you know GTK before you get too | |
83 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK. | |
84 | |
85 | |
86 SOURCE FILES | |
87 ============ | |
88 | |
89 about.c: | |
90 Not much to say here, just a few basic functions. | |
91 | |
92 aim.c: | |
93 This is where the main() function is. It takes care of a lot of the | |
94 initialization stuff, and showing the login window. It's pretty tiny | |
95 and there's not really much to edit in it. Watch out for bad Oscar | |
96 sign in hacks. | |
97 | |
98 away.c: | |
99 This takes care of most of the away stuff: setting the away message | |
100 (do_im_away); coming back (do_im_back); drawing the away window; | |
101 etc. To be honest I haven't looked at this file in months. | |
102 | |
103 browser.c: | |
104 Code for opening a browser window. Most of the code is trying to deal | |
105 with Netscape. The most important function here is open_url. Have fun. | |
106 | |
107 buddy.c: | |
108 This takes care of not only nearly everything buddy-related (the buddy | |
109 list, the permit/deny lists, and the window), but also a lot of the | |
110 code flow and util functions. Look for good things like find_buddy, | |
111 set_buddy, and signoff() here. | |
112 | |
113 buddy_chat.c: | |
114 This takes care of the buddy chat stuff. This used to be a lot bigger | |
115 until the chat and IM windows got merged in the code. Now it mostly | |
116 just takes care of chat-specific stuff, like ignoring people and | |
117 keeping track of who's in the room. This is also where the chat window | |
118 is created. | |
119 | |
120 conversation.c: | |
121 This is where most of the functions dealing with the IM and chat windows | |
122 are hidden. It tries to abstract things as much as possible, but doesn't | |
123 do a very good job. This is also where things like "Enter sends" and | |
124 "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The | |
125 chat and IM toolbar (with the B/I/U/S buttons) are both built from the | |
126 same function, build_conv_toolbar. | |
127 | |
128 dialogs.c: | |
129 A massive file with a lot of little utility functions. This is where | |
130 all of those little dialog windows are created. Things like the warn | |
131 dialog and the add buddy dialog are here. Not all of the dialogs in | |
132 gaim are in this file, though. But most of them are. This is also | |
133 where do_import is housed, to import buddy lists. | |
134 | |
135 gaimrc.c: | |
136 This controls everything about the .gaimrc file. There's not really much | |
137 to say about it; this is probably one of the better designed and easier | |
138 to follow files in gaim. The important functions are towards the bottom. | |
139 | |
140 gnome_applet_mgr.c: | |
141 A hideous creation from the days before I started working on gaim. Most | |
142 of it works, but it has functionsLikeThis. I hate looking at this | |
143 file, but I'm too lazy to change the functions. The best functions | |
144 are things like set_applet_draw_open, whose sole purpose is to set a | |
749
94edd99b7302
[gaim-migrate @ 759]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
708
diff
changeset
|
145 global variable to TRUE. [ note 8/22/00 - I finally changed this file. ] |
639 | 146 |
147 gtkhtml.c: | |
148 This is really just one big hack. It started off as an HTML widget that | |
149 was written for Gnome as far as I can tell. The current version is | |
150 huge, requires way too many libs, and is too hard to upgrade to. But | |
151 we've managed to hack this poor old version into basically what we | |
152 need it for. I recommend not looking at this file if you want to save | |
153 your sanity. | |
154 | |
155 gtkticker.c: | |
156 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that | |
157 widget. It's cool, and it's tiny. | |
158 | |
159 html.c: | |
160 Don't ask my why this is called html.c. Most of it is just grab_url, | |
161 which does like the name says; it downloads a URL to show in the | |
162 GtkHTML widget. http.c would be a more appropriate name, but that's OK. | |
163 | |
164 idle.c: | |
165 There is a very good reason why this file is still on version 1.1 | |
166 in CVS. The entire thing is #if 0'd out. I haven't ever really taken | |
167 a good look at it, but I think what it was supposed to have done is | |
168 set you as being away when a screensaver came on. | |
169 | |
170 network.c: | |
171 This has two functions: get_address and connect_address, both of which | |
172 call proxy functions. If you want to see how these are used, look at | |
173 toc.c and/or rvous.c. These are really just front-ends to the proxy | |
174 stuff; use these instead of calling the proxy functions. | |
175 | |
176 oscar.c: | |
177 One big hack of copied code. This is supposed to be the libfaim tie-in | |
178 in gaim. Most of it is just copied straight from faimtest, the small | |
179 program that comes with libfaim. I'm not even sure how half of it works, | |
180 if that makes you feel any better. | |
181 | |
182 perl.c: | |
183 This was basically copied straight from X-Chat through the power of | |
184 the GPL. Perl is the biggest, most confusing piece of C code I've ever | |
185 seen in my life (and keep in mind I'm a gaim hacker). I have a basic | |
186 idea of what's going on in it, but I couldn't tell you exactly. The | |
187 top half sets up perl and tells it what's going on and the bottom half | |
188 implements the AIM module. | |
189 | |
190 plugins.c: | |
191 This is the "plugin plug", as the file states. This file is probably | |
192 the only file in all of gaim that at the top has all of the functions | |
193 and global and static variables named out for you. It makes reading | |
194 it a little easier, but not by much. A lot of the code in here deals | |
195 with the plugin window rather than the plugins themselves. | |
196 | |
197 prefs.c: | |
198 The important function in here is build_prefs, but the most useful | |
199 function is gaim_button. build_prefs draws the window, and calls | |
200 gaim_button probably 30 or 40 times. (I don't really wanna run grep | |
201 | wc to count.) This is where you add the toggle button for gaim | |
202 preferences. It's very simple, and if you look at a couple of the | |
203 calls to gaim_button you'll figure it out right away. | |
204 | |
205 proxy.c: | |
206 This is where the bulk of the actual networking code is done. The big | |
207 function here is proxy_connect, which will connect through the proxy | |
208 setup you've chosen (most of which don't work...) or just regularly. | |
209 | |
210 rvous.c: | |
211 This was originally going to be the stuff for all of the Buddy Icon | |
212 and Voice Chat stuff, but I got really sick of protocol hacking really | |
213 quick. Now it only houses the file transfer stuff, which only works | |
214 for TOC. | |
215 | |
216 server.c: | |
217 This is where all of the differentiation between TOC and Oscar is | |
218 done. Nearly everything that's network related goes through here | |
219 at one point or another. This has good things like serv_send_im and | |
220 serv_got_update. Most of it should be pretty self-explanatory. | |
221 | |
222 sound.c: | |
223 The big important function is play_sound, which plays one of 4 (actually | |
224 6) sounds. One of the sounds is called in 3 different events, which | |
225 is why there are actually 6 sounds. This then calls play which then | |
226 checks for esd, then nas if that's not available, then falls back | |
227 to /dev/audio. | |
228 | |
229 ticker.c: | |
230 Syd is just so cool. I really can't get over it. He let me come | |
231 visit him at Netscape one day, and I got to see all of their toys | |
232 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
233 ticker. This is also a damn cool file because it's got all of the | |
234 functions that you'd want right up at the top. Someday I want to be | |
235 as cool as Syd. | |
236 | |
237 toc.c: | |
238 This handles everything TOC-related, including parsing gaim's buddy | |
239 list. Most of this file is toc_callback, which parses the incoming | |
240 information from the server. I really don't like TOC though. | |
241 | |
242 util.c: | |
243 There's not really a lot of cohesion to this file; it's just a lot of | |
244 stuff that happened to be thrown into it for no apparent reason. None | |
245 of it is particularly tasty; it's all just utility functions. Just | |
246 like the name says. | |
247 | |
248 | |
249 So that's our little tour of the internals of Gaim. It's really not | |
250 difficult to figure out if you've spent any time with GTK. I'm looking | |
251 forward to getting all of your patches :) |