This documentation is geared towards the configuration of grubby and basic understanding of its structure. For further reading, the Grubby User Manual and the Grubby Architecture Manual are available.
Grubby consists of the binary "grubby", the perl script "grubby-config", and many plugins (shared libraries). There are two groups of plugins: core modules, of which only one can be active at a time (to be determined at program startup), and normal modules, of which none to all can be loaded, and even unloaded and reloaded at runtime. Additionally, some scripts are available to be executed with either the embed or exec module, and then some data files and translated message catalogs. Everything should install fine.
All you have to do then is to call grubby-config, which gives you a full default installation. You might want to cut the options down, just edit the configuration files under $HOME/.ggz/grubby.rc. Then launch the bot while having a ggzd or IRC server running somewhere. If it fails, make sure you didn't cut too much options. Use netconsole.so as net core module to test for errors not relating to network protocols. Read docs/Setup for a full sample file, a short overview follows.
This is a minimal configuration file. By default it is expected to reside in $HOME/.ggz/grubby.rc. Entries which start with a hash mark (#) are optional.
[preferences] name = Grubby # Bot name #password = XXX # Password for registered grubby names language = en # Bot default language autojoin = 0 # Channel/room to join after login owner = you # Owner nickname host = localhost # Where to connect to #logfile = /tmp/guruchatlog #adminlevel = owner # Owner is the default; can be admin/registered/all too [guru] net = /path/to/libguru_netggz.so # or netsilc.so, netirc.so, netconsole.so player = /path/to/libguru_player.so i18n = /path/to/libguru_i18n.so #modules = self people ... [modules] self = /path/to/libgurumod_self.so #...
Grubby can communicate with users either locally (for debugging) or being logged into a GGZ, IRC or SILC server. The core module net can be configured appropriately:
The owner of grubby, as specified in the configuration, may issue some more commands than the other players. Here's a list of what the owner can do in relation to the loadable modules:
Grubby can be requested to log all communication to a log file. Also, the player database at ~/.ggz/grubby/playerdb is filled with entries when players join the room Grubby is in. These entries can be enhanced by the players with additional information using the player core module.
Some of the available modules are documented here.
This plugin executes external scripts and programs, writes to their stdin and reads from their stdout. It should be noted that the more external processes are spawned in serial order, the more time it consumes, and grubby may not react fast enough. Whereever available, execution via the embed module or even a native plugin (shared library) should be preferred.
The configuration of the exec module happens through the file $HOME/.ggz/grubby/modexec.rc.
[programs] programs = translate translate = /usr/bin/mytranslator --mode=grubby
Similar to exec, save it embeds the scripts directly. This works for Python, Perl, Ruby and Tcl so far and requires that support for those languages has been enabled at compile time. One advantage is that all commands are executed much faster.
The configuration of the embed module happens through the file $HOME/.ggz/grubby/modembed.rc, similar to the exec module, but with the identifier being scripts instead of programs.
[scripts] scripts = test test = /tmp/test.tcl
Grubby has the ability to launch game clients which have no GUI when commanded to do so. Those games are registered like normal GGZ game clients, except that their frontend is set to 'guru'.
The following scripts are distributed along with grubby (but others can easily be added). The corresponding interpreters should be installed to use them in exec, or the embedded interpreter support should be compiled in to use them in the embed module.
Several news sites offer RDF files which contain all headlines and links to the articles in XML format. Now when the user requests news from one of those sites, the module first fetches the latest RDF file from the target host (needs the perl module Net::Telnet installed), and randomly seeks one of the headlines which is to be returned.
This module is presentated by the perl script "dict.pl", which in turn needs several dictionaries installed, or at least one of them. Under Unix, those are mostly under /usr/share/trans/X-Y, where X and Y are lowercase language letters, like "en" for English. The dictionary files contain key:value pairs of words. Now when a search is done, the module simply opens the appropriate file and scans it. In the case of inverse search, key and value are swapped. The module returns a concatenated string which contains all translations it found for the key word.
This one needs Ruby installed, preferably version 1.6+. Its configurable database goes normally to $HOME/.ggz/grubby/meeting, similar to others. It uses an interesting technique to store its data: Instead of writing key-value pairs, it dumps the whole object so one can transfer it from one host to another.
In case common shell tools (cut, grep, ...) and wget are available, the script webtranslator.sh can be used for translations. It stores translated pairs of sentences into its cache (~/.ggz/grubby/google).