Gergely POLONKAI polesz@botcommander.hu 2005-2007 Gergely POLONKAI I dedicate this book to my girlfriend, as she was so patient while I wrote it. Part I: About BotCommander and this book Chapter 1: Who should read this book? Chapter 2: About BotCommander This document tries to explain the history and usage of the software BotCommander briefly. Everyone, who handles at least one eggdrop IRC bot Everyone, who wants to write addons (modules) for BotCommander Everyone, who wants to learn the script-writing methods for BotCommander BotCommander is a specialized telnet client, and a bit more. It is specialized in eggdrop IRC bot handling, enhanced with scripting possibility, and may also be enhanced with self-written modules (just like eggdrop itself). The project has its own homepage at http://www.botcommander.hu/ Command line history BotCommander has command line history. This means you can recall your previous commands with the Up/Down keys, edit them, and/or issue them again. Tabbed interface BotCommander has a tabbed interface, which means you can have several connections in only one window - just like an IRC, or IM client. Channel and user list If you have the correct permissions, you can have a list of the bot's users and channels; also you will be able to manage these: change user and channel flags and more. However, this feature requires a small TCL script to be loaded in the bot (that script is provided with BotCommander). BotCommander uses GConf2 to store its configuration, and all bot-related data. The graphical part (the widgets) are from GTK+ (currently using 2.6 features), and some are from libgnomeui. In this chapter you will learn about the installation methods of BotCommander. You will be able to install BotCommander under several Linux distributions, such as Debian and Gentoo, and also will know how to install it from the sources. For a few years, I was a hardcore Debian-user. Thus, it was almost my first task to create a Debian package out of BotCommander. I also created a Debian repository, so it is an easy task to install BotCommander under a Debian system. Just add the following lines to your sources list file. deb http://www.botcommander.hu/debian testing main deb-src http://www.botcommander.hu/debian testing main This snippet is only for debian etch (as of writing, at the end of 2006). After my Debian years, my next Linux-breed was Gentoo. It's absolutely does what the user wants (sure, if the user is smart enough). After a few days of coding, a Gentoo ebuild was born. It is the part of the BotCommander package, can be downloaded from http://www.botcommander.hu/, and I'm also trying to add it to the official Gentoo portage. If you are not the user of the above systems, then currently no package exists for your needs. I'm really sorry for that, but I always welcome if someone sends me a package for any OS-es. So, you arrived here, you want to install BotCommander from sources. This is good, but has some prerequisites: you will need bunch of software you may not currently have installed. I'm trying to make this list as correct as possible, but it may happen that I forgot about something. I'm really sorry if so. autoconf v2.60 This is required only if you want to compile the SVN tree, as it doesn't contain a configure script. gcc gcc is the GNU C Compiler. This is a necessary tool. gdk-pixbuf This is the GDK-pixbuf library, required by BotCommander to render some icons. glib This is the GLib library. BotCommander uses its memory-handling routines. GTK+ v2.6.2 or greater This is the GTK library. BotCommander uses its widgets heavily. libgnome2 This is the Gnome library. BotCommander uses some widgets in it. libgnomeui2 This is the Gnome-UI library. BotCommander uses the file open dialog from it. VTE This is the VTE (Virtual Terminal Emulation) library. BotCommander displays all the bot-messages in such a widget. GNU Gettext package This package is required for BotCommander to speak many languages. I'm trying to make this one optional, so one will be able to compile BotCommander without multilingual support (may be good for english-speaking people, and for minimalist systems) Throughout this part we assume that you install your bot yourself, and thus you have an owner flag in it. Many functions are not accessible, if you don't possess that +n flag. This chapter assumes that you have TCL installed system-wide. If not, please consult the eggdrop manual on how to install it for one single user, and how to make eggdrop use that library. I also assume that you know how to use the basic Unix/Linux commands, such as tar, thus you can unpack the eggdrop archive. First things first, you much fetch eggdrop from somewhere. The best place for this is eggheads' homepage at http://www.eggheads.org/. Download the latest version (as of writing, it is 1.6.18), and unpack it. Then enter the unpacked distibution's directory, and issue the following commands: ./configure make iconfig make After issuing make iconfig, that script will ask you several questions if you want to install this-or-that module. Read the module descriptions, and choose whichever you need. I'm currently planning to write my botcommander.tcl script as an eggdrop module. If I'm ready with that, I will instruct you how to compile new modules for eggdrop. After make finishes without errors, you can issue the last, make install command. This will install eggdrop to the given directory (if none was given, the default is $HOME/eggdrop. Configuring eggdrop is a long, yet not hard process, which requires almost no understanding of eggdrop, if you know english. The following is only a suggestion; contains my way on configuring an eggdrop bot.You may do it several other ways; it's up to you. However, if you read through this chapter, and follow my words, I will assume that the name you have chosen your bot is BCbot. First of all, enter the directory which contains your eggdrop installation. As said in the previous chapter, by default it is $HOME/eggdrop. After that, make a copy of eggdrop.conf with a filename as you will call your bot; then make it executable for at least yourself. cp eggdrop.conf BCbot chmow 755 BCbot Now begin to edit your newly created configuration. The most important thing (of course, if you follow my way) it the very first row, which now looks like this: #! /path/to/executable/eggdrop This tells the Unix/Linux shell to use /path/to/executable/eggdrop to interpret this file. Thus, the shell, instead of trying on interpreting the command in that file, will run the given command with this file as a parameter. Unless your eggdrop is at that location, you must change that line to something like this: #! /home/yourusername/eggdrop/eggdrop BotCommander doesn't have any defined command line parameters. This means that it accepts only the standard Gnome and GTK+ parameters only. I don't even have any plans on defining such things (yet). BotCommander has several built-in commands. These can be called from BotCommander or external scripts, thus extending BotCommander's functionality. Most of these commands can be abbreviated. This means that you can cut off the end of the commands, until it is obvious to the application. For example, as of the time of writing, the CONNECT command can be abbreviated as CON. There are some "dangerous" commands, such as QUIT, which cannot be abbreviated, so - in this case - you won't exit BotCommander if you accidently type in the Q command.

The QUIT command does what it should according to its name: exits BotCommander. If at least one connected tab is open, a small dialog will pop up, asking if you are serious about quitting. This command cannot be abbreviated.

This command closes the currently active tab. If there is an active connection in that tab, a dialog will pop up asking if you really want to do that. This command cannot be abbreviated.

This will open a connection in the current tab. It has many different invokations, depending on the parameters given. CONNECT without parameters will work if you previously assigned a bot to the active tab with the ASSIGN command. If so, the connection will be open to the given bot. CONNECT botname will connect to the named bot in the bot list. CONNECT host port will connect to the specified host, on the specified port. This can be useful, if you want to connect to a bot only once, e.g to check some settings or such. CONNECT host port username does exactly as the above command, but it will automatically send the given username also. This will be useful as the initial connection to a bot, as I'm planning to implement a SAVEBOT command, which will do just what it name suggests: save the current bot to the bot list.

The ASSIGN command does the same as CONNECT, with only one difference: it won't connect. It will assign all the connection parameters to the current tab, so when you are ready, you can use the CONNECT command without any parameters to do the actual connection.

The MODE command changes the current tab's mode. You can read more about modes in

BotCommander uses modes to distinguish between commands addressed to itself, and addressed to the connected bot. There are three modes, identified by their english names' first character. B, or BotCommander command mode (/) In this mode, entered text is validated against the commands built in to BotCommander, or commands provided by scripts and modules. E, or Eggdrop command mode (.) In this mode, text is sent to the connected bot (if any), so eggdrop itself will validate it. M, or Message mode (@) In this mode, entered text is sent to the connected bot. As you see, it is just the same as E mode, but there is a small difference. If the entered text begins with a dot (.), eggdrop would identify and parse it as a command. So in this case, the entered text is prefixed with a space. You can change between these modes in the Mode menu, or with hotkeys (Ctrl-B, Ctrl-E and Ctrl-M respectively). However, if you want to use one specific mode for a long time, and issue one line in a different mode, you can prefix your text with the character in parentheses in the above list. E.g if you use Message mode for hours, and want to issue one BotCommander command, you can do it by entering /COMMAND. As this happens, BotCommander will parse and execute the given row as a BotCommander command, and return to message mode.