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.)
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 SVN, in the libs/ subdirectory. If you add $COLOSSUS_HOME/libs to your CLASSPATH, you can use these tools without further configuration.
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 Java version 1.5.0 or newer; thay are nowadays named e.g. "JDK 5.0". Currently downloadable is update 14 ("Java Development Kit 5.0 Update 14") which would present itself then as something like "1.5.0_14". 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.
We use Subversion , with the repository hosted on SourceForge .
SourceForge requires using ssh as a transport mechanism, which complicates setup a bit. There are a lot of svn + 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 anything else, use OpenSSH, which should already be installed.
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 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.
Part of the JDK, keytool is need to generate a keystore that will contain your personal keys used to sign jars.
The Ant build.xml file has been configured to use a keystore named ${user.name}Keystore which must contain an alias ${user.name}.
The keystore password will be loaded from the local_build.properties key storepass.
To create the keystore file open a command prompt in the Colossus directory and run the following:
keytool -genkey -alias %USERNAME% -validity 999 -keyStore %USERNAME%Keystore -storepass pick_a_password
Follow the prompts to answer the questions and you will have a keystore setup
If you are testing locally then a default keystore has been provided and will be used to dummy sign the jars.
The web deployed files must be signed with your keys (and not the dummy ones).
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 (See keytool above).
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.
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 SVN, 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)
(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.
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.
Currently all images used in Colossus are GIFs or PNGs. 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.
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.
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 SVN.
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 .