How To Run Your Own Gump

Please note that this documentation specifies the plans we have, rather than what we actually do right now. The key difference is that Gump will be made much more intelligent about whom to send what e-mail and what to put in those e-mails. However, the basic ideas for all this are quickly falling into place.

Why do it?

Maybe you want to use gump on your own software that isn't built by gump itself (perhaps its closed-source). Maybe you're a gump developer and you want to test out changes locally. Maybe you just want to understand better how gump works. Maybe you want to run a copy of the main gump installation using a different operating system. There are lots of reasons, really.

Required knowledge

To be able to run gump you should have understand the basics of what gump is all about. You should also have some experience with cvs, subversion, the command line and xml. Python experience is not required.

Required software

Gump needs a unix-like environment. Prerequisites include:

Optional software includes:

The gump command line tool tries to be intelligent about detecting the availability of these tools. As long as you have bash, cvs, svn and hostname available it should be able to guide you to the right locations for getting these libraries.

For Debian users, it is mostly possible to mirror the main gump installation by following the procedures described on this page.

Downloading the sources

Gump doesn't publish distributions. Instead, you need to check it out from cvs/svn:

$ mkdir ~/gump/local
$ cd ~/gump/local
$ svn checkout https://svn.apache.org/repos/asf/gump/trunk .
$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
# password is "anoncvs"
$ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout gump
$ mv gump/* metadata
$ rm -Rf gump

Setting up your environment

The next step is to let gump know about your computer. Create a file named ~/gump/local/cron/local-env-${HOST}.sh, where ${HOST} should be replaced with the short name of your computer (ie the part before the first "."). You can find your hostname using the command hostname -s.

This file is a bash script which gets read by gump everytime it is run, before it does anything significant. In it, you can define environment variables by exporting them. For now, we'll define only the required GUMP_HOME and a JAVA_HOME because we will be building a java project:

export GUMP_HOME=~/gump/local
export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

The gump command line

Your main interface into gump will be the command line program named, aptly, gump. You can find out about its basic functionality using the "help" command:

$ cd ~/gump/local
$ ./gump help

      Utility commandline interface for Gump.
     
      Usage:
        ./gump command [opts ...]
     
      Available commands are:
     
        run -- run Gumpy
        test -- run Gumpy its unit tests
        get-metadata -- Check out or update metadata from CVS
        validate -- validate the metadata
        help -- print this information
        site -- use Apache Forrest to build the documentation
        site-publish -- use SVN and SSH to publish the site to the website
     
      Run
     
        ./gump help [command]
     
      for more information about a particular command.

Note that you need to cd into the GUMP_HOME directory before executing this command. (Yes, we know that's annoying.) One thing you might wish to do is use a small wrapper script that you place elsewhere, ie you could create the following as ~/bin/gump (assuming ~/bin is on your path):

#!/bin/sh
#
# Simple wrapper script which fires off gump
olddir=`pwd`
cd ~/local/gump
./gump $@
cd $olddir

Setting up the mysql database

Gump uses a mysql database for storing lots of interesting data about the build results. Create a new database named "gump", then populate it with lots of tables by importing the mysql/gump.sql dump into your new database:

cd ~/gump/local
mysqladmin -u root create gump
mysql -u root gump < mysql/gump.sql

Running the unit tests

Next, we'll run the gump unit tests using the command line interface. It would be nice if these tests would all always work, but this isn't the case, so simply don't worry if some of them fail:

cd ~/gump/local
./gump test

If the test suite gets run, that means you have all the neccessary prerequisites available. Finally! Now comes the fun bit.

Defining a workspace and a profile

Gump reads an xml file from GUMP_HOME/metadata that should be named ${HOST}.xml. This file defines a workspace, where you can customize just about everything about gump's behaviour. For now, simply copy the minimal-workspace.xml file that's in CVS into ${HOST}.xml. This file references a profile definition. The profile defines what stuff gump will build. The file referenced is profile/minimal-profile.xml, which builds Apache Ant, and nothing else.

Unless you're connecting to a database named "gump" as the root user without using a password, you'll need to customize the <database> field inside that profile to reflect your actual settings.

Running gump

Pfew. You're still here? Good. Let's do an actual "gump run":

cd ~/local/gump
./gump run

This will take quite a while, with surprisingly little output on the screen. Because gump is architected to be run from cronjobs, it sends all its output to logfiles. The main one to look at for now is log/gump_log.txt. However, most of the gump logs are output as HTML, so you'll normally will want to take a look at log/index.html using your web browser. Be aware that every new gump run overwrites these logs so if you want to keep a particular run make sure to make a copy of the logs somewhere.

It doesn't work!

Don't worry, that's normal :-D. Since gump is about "bleeding edge" by design, things tend to break a lot. Just pop on over on the general _at_ gump _dot_ apache _dot_ org mailing list and ask what's going on.