Go back...
[AOL IM logo] [GTK logo]
GAIM: Users Guide

Users Guide

Author: J.Crawford <jacrawf@oz.net>


This is meant to be a fairly straight-forward guide to the use of GAIM, the GTK+ AOL Instant Messenger clone. I'll cover where you can fetch it from, what's required to successfully compile and install, and the basics of using GAIM. This isn't deep stuff, so just about anyone should be able to follow it (especially if I dummy like myself can write about it).

Getting Set Up

Fetching the Source

You can find the newest version of the GAIM sources at <ftp://ftp.marko.net/pub/gaim>. As of now, the most recent sources are here.


I was able to successfully compile GAIM with no hitches on a very stock Red Hat 5.1 Linux distribution. However, there is a caveat to this. RH5.1 includes the GTK+ 1.0.1 libraries. If you compile against these libs, GAIM will look just fine, however it will probably run much slower for you. For best results, go for GTK+ 1.1.2 or newer. You can find the newest GTK+ libs in RPM format at the GNOME ftp site or one of it's mirrors.

Generally, GAIM should build successfully on an Linux-i386 2.0.35 glibc system with GTK+ 1.1.2 libs. If you can get it to build elsewhere, by all means let me know and I'll put up a list along with notes (if any).

Compile, compile, compile

I'm assuming here that you know how to untar a tarball. But just in case, this is how you would go about it: tar xvzf tarball.tar.gz. Then cd into the directory that was just created by untarring.

For the stock GTK+ version of GAIM, simply type make. Easy, huh?

To compile GAIM with themes support, uncomment 'USE_THEMES' in the Makefile.

For those of you who are having fun playing with GNOME, you can build GAIM as a GNOME-ified applet by uncommenting 'USE_GNOME' instead. Be sure to su to root and do a make install after compilation and you'll now be able to find GAIM in panel->add applet->Amusements->Gaim.

Running GAIM

Now that you've built GAIM with (hopefully) no error messages, simply type ./aim and you'll be on your way to Instant Messaging fame! You may also want to copy the executable (aim) to a directory in your path such as possibly $HOME/bin or /usr/local/bin. You won't need to do anything with any of the other files in the build directory.

Let's Go!

Now that you're running GAIM, let's go through the steps to get you going.


Unless you've use Instant Messenger before, you'll need to register a "Screen Name" so that you can communicate with all those other wonderful [sic] AOLers and other taking-advantage-of-the-establishment types such as you and I. At the GAIM Login window you'll notice a button which reads Register. If you click it and you happen to have Netscape on your system, you'll be directed to this URL. Ignore the sickening, patronizing animated image of supposed dialogue between 'Chris' and his pal 'Ray', and chase the nearest "Sign up NOW!" link. (Or, alternately, chase this link to head straight to where you need to be.)

You're going to need to be either very creative, or be willing to settle for a non-sensical alphanumeric combination for your "screen name" as just about all proper names, and even most dictionary words, have already been taken. You will also need a valid email address to confirm your registration.


Now that you've entered your registration information and replied to the email that AOL has undoubtedly sent you, it's time to log in! Just type your screen name in the appropriate box, your password in the appropriate box (if you compiled GAIM against the GTK+ 1.1.x libs, you'll see asterisks echoed back to you; but if you compiled against the GTK+ 1.0.6 libs that come with RH5.1, you won't see anything echoed back to you) and click the Signon. If you so desire, you can select the options to "Remember Password" and "Auto-Login". There are, of course, some security issues in doing this (grep the .gaimrc file that GAIM automatically places in your $HOME dir to see what I mean) so be sure of what you're doing. In any case, you'll want to do a chmod 0600 .gaimrc. This will be fixed in the next release of GAIM.

Also, just so you know, the Cancel button quits GAIM, just do you aren't disillusioned if you click on it thinking it does something else.

The Buddy List Window

File -> Add A Buddy

Now you've logged in but you don't see anything in your buddy list? Let's fix that.

Click File -> Add A Buddy. In the window that appears, type the screen name of the person you'd like to add. You'll also have a chance to change the group you add that person to as well. It should default to "Buddies", but you can type any other group name here or select one that you've already set up (if you've set any up) via the drop-down list. Now, when your buddy is logged in to AOL's IM servers, you should see their name manifest itself right there on your list.

Also, your buddy list is actually saved on AOL's servers, so if you go looking for a plaintext file to edit, you won't find one. This is actually for a very good reason. Say, for instance, that you are using GAIM at a friend's computer: you log in and due to the fact that your buddy list is saved on AOL's servers instead of in a text file on your hard disk, even at your friend's computer you'll still have the exact same buddy list.

File -> Edit Buddy List

Did you make a boo-boo? Click File -> Edit Buddy List to go and fix it. From here you can add and remove buddies. Obviously, clicking on "Remove" removes that name and clicking on "Add" does the same thing as File -> Add A Buddy. I'll leave it as an exercise to the reader as to what the "Close" button does.

File -> Edit Permit/Deny

This hasn't been implemented in the available snapshots yet. We'll be sure to let you know when this happens!

File -> Signoff

Signs you off and returns you to the Login window.

File -> Quit

Goes one step further and obliterates GAIM from your X session. Don't blame us if you immediately suffer an advanced case of panic and withdrawl from discontinued use of GAIM; it's a thoroughly documented medical affliction and your nearest veterinarian should be able to give you a shot to make it all better (of course, a good de-worming will probably be in order also, for which you will be billed later). We take no responsibility for any ill effects from the use or disuse of GAIM. :)

Tools -> Preferences

This is where you change some of the more global preferences.

* "Enable buddy logon/logoff sounds" - Changes whether or not you hear those sounds. This option doesn't do much good for you if you don't have a sound card or sound compiled into your kernel or your speakers turned on.

* "Enter sends message" - Do you want to just hit the enter key or do you want to have to specifically click on "send" every time you want to pop off an instant message?

* "Enable send/receive message sounds" - Rather like the logon/logoff sounds option; this one will toggle whether or not you hear the sounds that can accompany message send or receipt.

* "Show time on messages" - Time-stamps messages in your chat window. Fairly useful if you're like me and running around the room like a maniac every few minutes just so I don't get that perma-butt impression in the chair.

Tools -> Away

If you're going to step away from your computer for a while, but don't want to shut GAIM down, then this is the menu item for you! While you have an away message up, anyone who IMs you will be greeted with this automatic reply. Dazzle your co-workers! Amaze your friends! Be the first on your block to use it! Or something.

Tools -> Away -> New Away Message will add a brand-spanking-new away message. Make sure the title that you enter doesn't contain any whitespace characters, or the label for your away message will be broken looking. The actual away message itself can have whitespace characters in it though, so don't worry about that.

Tools -> Away -> [Previously used message]: when you add a new away message, you'll be able to use it again just by clicking on it's title in the Away submenu. Spiffy, eh?

Help -> About

Information about GAIM. Perhaps one day there will be more extensive help here in the Help menu (like maybe a User's Guide *cough, cough*).

The buttons at the bottom

This bit is another easy bit: the Im button opens up a dialogue for you to send an Instant Message (hence the labelling of the button as "Im") to whichever buddy you happen to have highlighted at the time.

The Info button loads a page chock full of wholesome information about the buddy you happen to have highlited in a Netscape window if you happen to have Netscape installed. (If you want it, go to Netscape Communication Corp.'s website and fetch it. However, if you're a Lynx user (and nearly all of us are at some point or another, right?) then I suggest you follow this link to their ftp site and find it that way. Their website looks like crap in Lynx and you'll never get anywhere. Of course, if you're using Lynx, you may not even have an X display to run Netcape in, so I *could* just be typing all of this in vain. I'll hope not.) If you don't have Netscape, this button might not work for you.

The Chat button opens up a dialogue to join a chat. And that leads us to...

Group Chats

You clicked the Chat button in the Buddy List, didn't you? And because you did that, you might possibly be wanting a bit of information on what the heck is going on. Here is all the ancients had to speak of upon these matters:

Join Chat

The first dialogue you encounter will ask you "Join what group:".

(Ok, so technically it wasn't a question since a so-called "question mark" didn't exist in the phrase. So what? Normal spoken dialogue between humans is filled with logical errors as well. An example would be, "He ain't got no something-or-other" when the question is heard to mean, "He does not have any something-or-other". So, are you still going to jump down my throat about this?)

If you know the name of the group you want to join, then type that here and click on the Join button. However, if you want to create a new group, you can type the name of your new group here, click Join, and it will be created. And lastly, if you don't have anything better to do, you can just type in random names and alpha-numeric combinations here and see if you can catch anyone in a particularly embarrassing conversation. (I hear the group "kittypr0n" tends to have some interesting goings-on, most of which involve poor felines, cameras, mayonnaise, and juggling acts. I wonder if the authorities have caught on to this insidious group yet?)

The actual chat itself

After you click on Join you will be presented with a new window with a layout very reminiscent of mIRC or Xircon or any other number of IRC programs for Windows 9x. (No, I am NOT admitting I've ever had any involvement with any Microsoftian OSes here. Er. Not ever. Well...ok, I did once, but I didn't give it anything it asked for! I still have nightmares about how it touched me. Eeugh. <shiver>) There will be a list of the names of people who are currently involved with the chat on the right, a big box where all the dialogue goes on the left, the input line and a bunch of buttons on the bottom.

Basically, just type what you think others would like to read or expect to read from you in the input box and hit enter to send it (or click the Send button if you disabled "Enter sends message" way back in the Preferences).

The buttons

* Send - We already covered this one, didn't we?

* Whisper - If you've typed some text in the input box but you'd like for it to only go to one of the people in the group instead of being broadcast everywhere across the land like you're some sort of ignorant pig who doesn't care about the right of anyone else in the world...sorry, I was just venting. Start again.

If you only want one person to read what you have typed in the input box, highlight their name in that box on the right and then click the Whisper button. Of course, you could always just send them an Instant Message too, but apparently AOL likes to support redundant features just for the hell of it. Don't blame Jim, Mark, or Peter; they're just supporting that particular "feature"!

* Invite - Click on this button and you'll be prompted to invite someone to the group you are chatting in with a message. Just type in your buddy's name and then a short message probably telling him/her why you want him/her to join. Just mention kittypr0n. That'll get their attention.

* Close - Another instance where I shall leave it as an exercise to the reader as to what this button does.

Instant Messaging

Here is the guts of Instant Messaging. It is a skill easily learned, but difficult in the mastery. I shall lead you as best as I may, grasshopper.

Send IM

When you highlight a buddy's name in your Buddy List and then click Im, you'll be presented with a cute little window in which to enter text and to either Send it or Cancel the whole thing altogether and go home and sulk. Type in what you want to say then click the appropriate button. What could be simpler?

The Art of Conversation

Once you've received an IM, a window will pop up proclaiming "Conversation with [Buddy name]". There are three parts to this: the main text window, some fluffy buttons, an input box, and more (non-fluffy) buttons with entirely different purposes.

The main text window

This is where you'll see both what you've sent for your buddy to see and also what your buddy sends back to you. And if you were a good girl or boy and turned on time-stamping, you'll also get to see when these transactions took place.

Fluffy buttons

These buttons will let you apply various different effects to your text. Basically, they just insert some HTML tags into your input box, so you can always feel free to just type in those tags normally. The supported tags are:<B><I><FONT> It is worth noting that the only supported modifier in the <FONT> tag that I am aware of is the "size". Example: <FONT size="3"> will produce a normal sized font. The sizes 1, 3, and 5 are the oft used ones.

Text formatting is for weenies.

There is also a button there that is reminiscent of a speaker. That button toggles the sounds for that particular conversation window. So, you can block out the interrupting sounds from pests with whom you don't particularly want to chat with but whom you also do not want to totally snub by telling them to go and molest some livestock, and yet you can also hear the interrupting sounds from those ultra-spiffy people whose conversation you particularly enjoy.

Sound is for weenies. (Yes, I'm a hypocrite!)

Input box

Er, type what you want to send in this box. Yeah. Something like that.

More (non-fluffy) buttons

* Send - This sends your text. You won't need to use it unless you really need to.

* Info - This does the same thing as the Info button in the Buddy List.

* Warn - This is un-implemented in the current snapshot, however it will eventually do the same thing as the official AIM counterpart function. Namely, tattle-tale on whomever you're chatting with because they were being bad.

* Color - This is also un-implemented in the current snapshot but I'm sure it'll change the color of something.

* Add - Adds this person with whom you are conversing to your buddy list if they do not already happen to exist there.

* Close - Aargh! There is that darned button again!

Known Bugs

There are a couple, so pay attention!

Removing groups

Currently, it isn't possible, so pick and choose with care what groups you have because you won't be able to remove them for the moment. No one on the ranch seems to know what it is since that feature used to work, but now does not.

Away messages

The bit about your away message titles not being able to have any whitespace characters in them is, IMHO, a bug. But, of course, I'm just the web monkey around here and don't grok C (yet).

Also, there is a wee bug with adding new away messages. The first one you add will go fine. You'll type in everything properly and then you'll click on Away! and everything will be hunky-dory. BUT, from then on in, when you add new away messages and click Away!, the away message you had been using immediately previous to the new one you entered will be the one shown. You'll just need to cancel the away message and re-select it from the list of previously used away messages.

Finally, you can't erase away messages that you don't want any longer from GAIM. If you want/need to do that, you'll need to edit your .gaimrc file that is placed in your home directory. I'll use my .gaimrc file as an example:

user FlynOrange
sounds 1
extrasounds 1
enter_sends 1
show_time 1
remember_pass 0
auto_login 0
away_mess I've_stepped_out.
I've stepped out.
away_mess Webmonkey
The web monkey is doing his work here! Whaddya want?
Why, it looks exactly like all of your options, doesn't it? That's because it is. Now, according to my .gaimrc file I have two away messages suitable for immediate use: I've_stepped_out and Webmonkey. But let us say that I no longer find the Webmonkey one very interesting. I'd need to erase these two lines out of my .gaimrc file:
away_mess Webmonkey
The web monkey is doing his work here! Whaddya want?
I'm sure I didn't even need to tell any of you which lines to remove, did I? Slap me.

Instant Messenging

Aside from the buttons which are currently not implemented, there are problems with with the font-resizing buttons. They're broken, big-time. The tags get totally mangled and they don't fit the text they're supposed to in between the tags in any case. And even if they did, the syntax for sizing is wrong. It'll try and make the font larger, regular sized, or smaller by appending size="+5", size="+3", and size="+1" respectively. That is plain wrong. The correct formatting is to scratch the + characters and use the flat decimals. If you know your HTML tags, you'll know that +n means to increase the font size by that many increments.

Other stuff

If you happen to have compiled GAIM against the GTK+ 1.0.6 libs (which isn't recommended because you'll likely just have problem after problem) you'll notice that 1) it takes forever to load GAIM and 2) that after you've opened the Help -> About dialogue (which will take quite a long time, which it shouldn't) a few times, it'll eventually cause GAIM to crash (not to mention the other intermittent crashes you might experience). The answer? Don't use the GTK+ 1.0.6 libs. If you're having any problems whatsoever with GAIM, make sure you've compiled against the latest libs. If you have not, don't bug Mark, Jim, Peter, or myself.

The GTK+ libs are currently numbered in the even-odd, stable-development fashion that the Linux kernel is, and since the 1.1.x libs are therefore still under development, it might just be the version of the libs you have. I myself compiled GAIM against the 1.1.2 libs and have had no problems and Mark has compiled against the 1.1.9 libs with no problems. However, you may have also sighted a drastic short-coming in the code. In that case, please submit a bug report, or better yet, write a patch! (Don't submit the patch to me, however. I can't do anything with it. Email Mark or Jim about that.)

Closing up shop

I hope that this User's Guide has been helpful. If you have any comments or suggestions, or if I've made some sort of drastic error in here, by all means email me and I'll get right on the case. Have a good time Instant Messenging!


Users Guide ©1999 J.Crawford
GAIM ©1998,1999 Mark Spencer

Web page designed by J.Crawford <jacrawf@oz.net>