# Building Colossus

Sorry this is so longwinded; we're trying to be thorough in case someone who's not a Java programmer wants to make a small change. (If you already know C++ you can learn basic Java in a weekend; the hard part is learning all the tools.)

## Tools needed

All of these tools are free downloads, and we need to avoid making the game depend on tools that aren't.

Where practical (a combination of friendly licensing and reasonably small size), we now put the tools in CVS, in the libs/ subdirectory. If you add $COLOSSUS_HOME/libs to your CLASSPATH, you can use these tools without further configuration.

#### Java development kit

You need a JDK , which includes a javac compiler, a Java runtime environment, and various utilities like jar and javadoc. The game should work with JDK 1.4 or newer. 1.4.2 seems to be the most stable. Unless you have a great net connection, also download the JDK docs, which are packaged separately.

Sun maintains the best-known (and IMO best) JDK for MS Windows, Solaris Sparc and x86, and x86 Linux.

The Blackdown JDK is the original port of Sun's Solaris JDK to Linux. Sun's Linux JDK in turn now uses Blackdown code. So the two are very close cousins. If you have a non-x86 Linux box, you want Blackdown.

If you use MacOS, you want the Apple JDK.

Unfortunately, the free gcj and kaffe projects don't yet have enough GUI support yet to be useful for Colossus. Maybe someday.

If your platform is not listed above, a starting point for finding a JDK is java.sun.com/cgi-bin/java-ports.cgi

Once you have installed your JDK, you probably want to set an environment variable called JAVA_HOME that points to its base directory. Then you want to put $JAVA_HOME/bin in your PATH . You also want to set CLASSPATH to include . (the current directory); you'll add stuff to it later as you add Java tools. A few tools directly use JAVA_HOME. It also lets you easily switch JDKs by changing one environment variable.

#### Other compilers

Jikes is a very fast Open Source Java compiler originally written by IBM. I don't recommend using it anymore, because it produces slightly different class files than javac. If you need the speed, the combination of Ant and Javamake helps a lot by compiling all files in one Java process, and only recompiling the files that need to be recompiled. The JavaMake jars are included in the Colossus libs/ subdirectory; include it in your CLASSPATH.

#### Build tools

Ant is a newer cross-platform build tool used by many Java projects. It's fairly fast because all compiles are done in one Java process. It uses a file called build.xml . You need version 1.5 or newer. You'll need to set ANT_HOME to its install directory, and you'll want $ANT_HOME}/bin in your PATH .

Javamake is a Java dependency checker from Sun Labs. It allows us to recompile only the classes that need to be recompiled.

#### Source code control

We use CVS , with the repository hosted on SourceForge .

SourceForge requires using ssh instead of the insecure pserver as a transport mechanism, which complicates cvs setup a bit. There are a lot of CVS + ssh setup directions on SF . If you can't get it to work, ask for help.

If you're using Windows try PuTTY for a good free SSH/Telnet client. . If you're using Unix (bash syntax, I assume you can convert to csh or whatever):

        export CVSROOT=username@cvs1.sourceforge.net:/cvsroot/colossus
        export CVS_RSH=ssh

If you're using Windows:

        set CVSROOT=username@cvs1.sourceforge.net:/cvsroot/colossus
        set CVS_RSH=c:/putty/plink.exe
        set PLINK_PROTOCOL=ssh

#### Java Web Start

If your JDK didn't include Java Web Start , you want that too, so that you can test that you haven't broken JWS compatibility. (This is way too easy to do when you add resources.) Add javaws to your PATH .

#### jar

Jar is the standard java archive format. It basically uses the compression algorithm from zip with command line syntax similar to tar. If you need to uncompress a jar file on a machine with no jar, try your favorite unzip tool. (But this may mess up permissions on a Unix box.) Jar comes with the JDK.

#### jarsigner

Jars can be signed. Jars must be signed to work over Java Web Start. But note that you can use "test" keys -- you don't actually have to pay money to a certifying authority and get a "real" key that actually "proves" that you are who you say you are. The jarsigner tool comes with the JDK. To use it, you need to create a personal authentication key, and put it in a keystore file. The sign target in build.xml assumes that your key name and keystore filename match your username. If you don't like this, you can add new targets.

#### zip and unzip tools

You need something that can work with the standard zip format. WinZip, Info-Zip, PKZip, etc. Info-Zip is free -- most of the others are shareware. In a pinch you can use jar to manipulate zip files.

#### Text editors

Your choice. It's a matter of taste. I recommend choosing something that autoconverts tabs to the right number of spaces on the fly. (Tab characters in code are evil ; this is not a matter of taste.) and can save files using Unix newline and end-of-file conventions. If your editor can't do these, then you'll need to run ant fix on your code before checking it into CVS, to avoid creating whole-file false diffs or files that look awful if someone has different tab stop settings than yours. (Yes, cross-platform development adds a few wrinkles.) Two popular, powerful, free, portable editors are Vim and XEmacs Xemacs can use the Java Development Environment for Emacs (JDE)

## Optional tools

#### Debuggers

(As any experienced programmer can tell you, the general problem with debuggers is that they work great with simple code but tend to fall over with complex, multithreaded, distributed code. So don't expect too much.)

JSwat is free and pretty good.

ODB is new and still somewhat rough, but looks very promising.

#### Profilers

You can use java -Xprof .

Or maybe try HPjmeter

I tried Extensible Java Profiler Very nice interface, but it was way too slow to be usable for Colossus, presumably because it records every instruction rather than a sample.

#### Code reformatters

If you just can't work with our format then you need a tool to convert files to and from your personal pet format to the one this project uses. Jacobe is free (but not open source) and works pretty well. It's available for Windows and Linux. See CVSROOT/colossus-jacobe.cfg

Another one that looks promising is Jalopy

Unfortunately, neither breaks long lines perfectly.

#### Image editors

Currently all images used in Colossus are GIFs or PNGs. (Though we're starting to experiment with SVG.) JPEGs are great for photos but not optimal for simple drawings. Any image editor that can save to standard formats is fine. If you don't have one, The Gimp is good and free, but has a steep learning curve.

TODO Find a lighter-weight, easier-to-learn, free image editor.

#### Testing tools

We've added a few unit tests using JUnit . We need to add more. The JUnit test classes are the ones named *Test.java The ant test target runs all tests, using the JUnit text UI. We now include junit.jar in the libs subdirectory, so it should be easier to add tests.

## Build process

Once you have the tools set up, Colossus basically builds itself.

First you need all the source files. Snag the latest zip file from http://colossus.sf.net/download/ or (to get the newest possible code) pull from CVS.

If you just type ant from the project base directory, then you get the default target, which will compile all the .java files into .class files with javac, then make an unsigned executable jar file.

Other interesting targets include clean and fullyclean (delete stuff, useful if you want to clean up or make sure that you fully rebuild all your class files), fix (does a bit of text reformatting on java source files), tools (builds standalone tools), sign (signs a jarfile), and dist (makes a zip file).

There are also some targets that automate installing the package onto a web site -- these are designed for maintaining the SF site rather than general use.

Basically, skim through build.xml .