Robocode/Developers Guide for building Robocode

This guide describes how to build the Robocode application, i.e. the game itself, and not how to build bots for Robocode.

Developer's Guide for building Robocode with Eclipse setup

Notice

This guide is intended for experienced Java developers, who want to work on the Robocode application, and describes all basic stuff required to compile and run Robocode within the Eclipse IDE.

If you just need to browse the sources, you can do it from here or you can download the zipped sources from here.

Requirements

Basically, all you need to get started with building Robocode is:

• Oracle JDK 8 (Java SE Development Kit 8 Downloads). Note that only version 6, 7, and 8 will work. Newer versions are not supported (yet) and are almost guaranteed to cause building problems.
• Source files for Robocode (on GitHub), which you get by doing a Git clone.
• An Internet connection.

Other than that, you need to be a skilled Java developer in order to figure out how Robocode is put together. Robocode is a complex application and requires a big effort to grasp and understand. There is practically no documentation available that describe the internal logic, architecture, game rules, coding conventions etc. So you will probably be on your own when trying to figure out how Robocode it put together.

An Internet connection is required for building Robocode distribution files as the build tool (Maven) needs access to remote repositories, which contains various libraries and binaries. Some libraries are used for building Robocode, and others are used for running Robocode, and hence need to be put into the distribution files. In order to get updates to the sources of Robocode when new versions emerge, an Internet connection is also critical to download changed sources and merge the changes with your version of the sources etc.

Note that all sources of Robocode are for Java 6, meaning that Robocode is able to run on very old Java versions, which is intentional.

Installing the JDK

Robocode is being developed in Oracle's Java SE 6, and requires the Java Developer Kit (JDK) version 6 to be pre-installed on the system used for building Robocode. Please note that a Java Runtime Environment (JRE) is not enough as it does not contain the required developer tools needed for building Robocode.

The JDK 6 is used for the building official releases for Robocode even when this old version 6 has entered it's End-of-Life (EOL). The reason being that Java SE 6 is the minimum requirement when end-users needs to run Robocode, and due to the fact that the current build system of Robocode is known to cause problems with building Robocode with newer JDK versions (e.g. version 7 and 8). If you are unhappy about that, you are welcome to update the build system (including the part required for building the .NET plug-in for Robocode). ;-)

If you just want to play with the sources (without using the build scripts for Robocode), you could use a newer JDK 7+ if you want to, e.g. building Robocode inside the Eclipse IDE. But be aware that you might not be able to run your version of Robocode on older Java versions, if you builld your own version of Robocode. Another problem is that the .NET plug-in for Robocode needs to make use of the build scripts for Robocode and also requires additional Windows-specific tools to be installed on your system.

Notice that when installing the JDK, it is highly recommended that you install the sources provided for Java as the sources are very useful when debugging Robocode. However, this is not a requirement.

Setting up Java Environment Variables

You must set up the environment variable named JAVA_HOME and extend another environment variable named PATH.

JAVA_HOME must be set up point to the root directory of the JDK you intend to use.

The PATH environment variable must be extended in order to locate the Java commands like 'java', 'javac' and lots of other tools in the JDK. Extending PATH is considered best practice when setting up the Java development environment, and makes it possible for other tools like e.g. Maven to locate the proper JDK tools. It also makes it possible for you to detirmine which JRE that is being used when running a Java application by writting java -version in the command-line/shell, and detirmine which Java compiler that is being used by writting javac -version instead.

Windows:

• JAVA_HOME is set to e.g. JAVA_HOME="C:\Program Files\Java\jdk1.6.0_45".
• PATH is extended, e.g. to PATH=%JAVA_HOME%\bin;PATH.

Linux / *nix:

• JAVA_HOME is set by e.g. export JAVA_HOME=/usr/java/jdk1.6.0_45/bin/java. (Bash)
• PATH is extended, e.g. by export PATH=$JAVA_HOME/bin:$PATH. (Bash)

Mac OS X:

• JAVA_HOME is set by e.g. export JAVA_HOME=$(/usr/libexec/java_home).
• PATH is extended, e.g. by export PATH=${JAVA_HOME}/bin:$PATH.

If you want more information of how to set up your JAVA_HOME and PATH environment variables for your specific OS, please read the installation notes provided for the Oracle JDK here:

Installation Notes from Oracle:

• Installation Notes for Windows, Linux, Solaris, and Mac.
• Certified System Configurations for Java for all supported systems.

Required technical skills?

In order to develop on Robocode, you need to know the basics of these tools:

• Eclipse IDE (Tutorial)
• Git and GitHub (Tutorial)
• Maven (Tutorial)

Notice that you do not have to be an expert in Eclipse, Git/GitHub, and Maven. But you need some basic knowledge about these tools to understand how to build Robocode. In fact, trying to build Robocode might actually be a very good way of learning these tools, if you don't know them already or miss some practical experience with these. :-)

When you need to start editing the sources of Robocode, you naturally might want to use an IDE for compiling and run Robocode on the fly to quickly see the effect of your work. This is where Eclipse IDE comes into the picture for this guide, as many Java developers regards the Eclipse IDE as the best IDE for Java development. Eclipse comes free of charge, has a huge community, automatic compilation, a rich source code editor, a flexible window layout, and lots of plug-ins. Eclipse has been choosen as the primary IDE for building Robocode, and thus this guide only describes how to setup and build Robocode with this IDE. If you want to use another IDE for developing Robocode you need to figure out how to set it up by yourself based on the details from this guide. And you are more than welcome to add a page beside this article that described how to setup everything for IDE of your choise and link to it from this article. :-)

All sources of Robocode are available at GitHub. At GitHub, you can download sources as a zipped file or create your own clone/fork, if you want to.

Even though Maven is used as build tool, you don't need to pre-install it on your system. Batch (.bat) and shell (.sh) files are provided with the source files. These scripts will automatically download required libraries, scripts and tools required for building Robocode. Hence, no tools needs to be pre-installed in order to build Robocode beside the JDK and correct environment settings for JAVA_HOME and PATH.

Notice that the shell scripts (.sh files) should work under Unix and *nix like OSes including Max OS X. However, the shell scripts have only been tested under Linux (on Ubuntu), so there is no guarantee that these will run without issues on other *nix systems.

You don't have to worry too much about how to setup Eclipse for Robocode as the provided sources contains all configuration files needed by Eclipse. Some of these files are generated using Maven's build-in support for Eclipse. However, you will need to do some basic pre-configuration of Eclipse before you'll be able to get started with working on Robocode. You should only need to set up a workspace for Robocode once. However, you will need to update the sources from the remote repository on GitHub once in a while, and merge changes with your sources in order to keep up-to-date with the current versions of Robocode, i.e. the trunk/head of the Robocode sources.

Checking out sources from GitHub

In the following, I assume that you want to check out the sources from GitHub using some Git client. This could be one of the Git GUI Clients (git-gui) recommended here. You don't necessarily need a Git client for building Robocode, as you could simply get the sources from a plain .zip file. However, if you want to update your local source files with the newest sources from the Git repository and the ability to commit and/or merge changes, you will need to use some Git client in order to get access to files beside the files inside (Eclipse) project directories, e.g. if you want to check out the scripts located in the root of the Git repository for Robocode.

The URL of the sources at GitHub is: https://github.com/robo-code/robocode.git

How to build distribution files?

In order to build the distribution files containing the installer setup file (robocode-x.x.x-setup.jar) and a .zip file containing all the sources (robocode-x.x.x-src.zip) you must call the mvnassembly script from the command-line when standing within the root directory of the Robocode sources.

On Windows:

 mvnassembly

On *nix:

 ./mvnassembly.sh

This will build the distribution files, which will be put into the sub-directory named robocode.distribution/target.

mvnassembly is a script that compiles all sources of the Robocode game, creates javadoc html files, run test units, and finally creates the target distribution files. The first time this script is run, it will need to download a huge amount of .jar files from various Maven repositories and which contains Maven plugins etc. used for building Robocode. So please be patient with it the first time.

Setting up Eclipse for developing on Robocode

Here follows a description of how to setup Eclipse for developing on Robocode.

Software Requirements for Eclipse IDE

Here follows the recommended software needed to start developing on Robocode with the Eclipse IDE:

Required:

• Oracle JDK 6 (download) must be pre-installed.
• Eclipse IDE for Java Developers(download). The Juno, Kepler, Luna works fine for Robocode and supports Git.

Please consult the installation notes provided for Eclipse in order to find out how to install Eclipse for your specific OS.

Create a workspace for Robocode

When you have setup and installed Eclipse on your system (if you did not have it on your system already), a workspace must be created for Robocode.

The first time you start up a newly installed Eclipse, it will ask for a directory for your workspace. I suggest that you create a workspace named robocode-workspace or similar and create the workspace on a partition or directory like e.g. C: (on Windows) or ~ (on Linux) - or any other directory of your choice. If you have already got a workspace, e.g. the default one suggested by Eclipse, you can create a new workspace if you wish by selecting 'File' -> 'Switch Workspace' -> 'Other...' from the menu.

M2_REPO class path variable

One of the first things you need to do in Eclipse is to set up the M2_REPO class path variable for Eclipse, which points to your local Maven 2 repository. That is, Eclipse uses the M2_REPO class path variable for locating the Maven repository containing various libraries used for compiling Robocode etc. But before you can setup the M2_REPO class path in Eclipse, you must run the 'mvnassembly' command described earlier if you have not already done that.

When calling the 'mvnassembly' script or alternatively start off Maven within the root of the robocode sources by calling e.g. 'mvn clean install', Maven will download all required libraries from other sites into your local Maven repository. Note that you will need to locate your local Maven repository. Under Windows your Maven repository is put into your %USERPROFILE% directory, and on Linux is put into your home directory (~). The Maven repository will be put under .m2/repository.

To setup the M2_REPO class path in Eclipse, you must go to the menu bar and select 'Window' -> 'Preferences'. On the Preferences window expand the 'Java' -> 'Build Path' and select the 'Classpath Variables'. On the page for the Classpath Variables, you click on the 'New...' button, and enter M2_REPO as name. Next, you click on the 'Folder...' button and navigate to where you have your .m2/repository directory located (in %USERPROFILE% under Windows, and ~ under Linux), e.g. C:/Users/Flemming/.m2/repository (Windows) or /home/fnl/.m2/repository (Linux).

When Eclipse asks you if it should rebuild the workspace, you select 'Yes'.

Configure JDK for your workspace

You must setup which JDK that will be used for compiling (and running) Robocode in your workspace. You do this by...

1. selecting Window -> Preferences from the menu, and then unfold and select Java -> Installed JREs and press 'Add...' on the 'Installed JREs' page.
2. Select 'Standard VM' on the 'JRE Type' page and press 'Next >' or Enter.
3. Press the 'Directory...' button and browse to where you have installed your JDK 6 and press 'Finish' or Enter. Make sure to select a JDK and not a JRE, as a JRE is not sufficient as it lacks the tools available with the JDK.
4. When you get back to the 'Installed JREs' page, make sure to put a check mark in the JDK you just added and press 'OK' or Enter.

Importing sources of Robocode using Git

Importing the projects for Robocode into Eclipse from Git can be done from the Package Explorer, which can be opened from the menu by selecting Window -> Show View -> Package Explorer or by using the keyboard shortcut by pressing Alt+Shift+Q and P. In the Package Explorer, you...

1. Right-click the mouse and select 'Import...' in the popup menu that occurs.
2. Unfold 'Git' in the 'Import' window and double-click 'Projects from Git'.
3. On the 'Import Projects from Git' you select 'URI'.
4. On the next page named 'Source Git Repository' to enter https://github.com/robo-code/robocode.git into the 'URI:' text field and press Enter or 'Next >'.
5. On the 'Branch Selection' page you press 'Deselect All' and select the branch you want to work on. This would normally be 'master', which is the master branch of Robocode. When the branch selection is made, you press 'Next >' or Enter.
6. On the 'Local Destination' page, you must note the directory where your local files will be put. I recommend you use the directory suggested by Git (Eclipse) and press 'Finish' or Enter.
7. On the 'Select a wizard to use for importing projects', make sure 'Import existing projects' is selected and press 'Next >' or Enter.
8. On 'Import Projects', you should deselect the first project named 'plugins' as you would normally not want to develop on plugins for Robocode - otherwise just omit deselecting 'plugins'. Press 'Finish' or Enter.
9. All Robocode projects will now be imported into Eclipse and be visible in the Package Explorer.
10. Now, select all projects (press Ctrl+A) and right-click the Package Explorer and select Replace With -> HEAD Revision on the popup menu that occurs, and press 'OK' or Enter to discard local changes on the dialog that appears.

Congratulations, you should now be able to get started working on the Robocode sources in Eclipse. :-)

Launch Robocode

Before launching Robocode for the first time, you should make sure that it is cleaned and compiled first. You do this by selecting Project -> Clean... from the menu. You should also make sure that you have run the 'mvnassembly' described previously, which will download and update your local Maven repository, which is necessary for compiling and running Robocode.

Please notice that it might be necessary to refresh the sources in Eclipse when files are changed outside the Eclipse editor, which is the case when running the 'mvnassembly' script. You can do this from the Package Explorer by right-clicking in this and select 'Refresh'.

In order to start running or debugging Robocode, you should select the "Bug" (debug) or "Play" (run) button in the top of Eclipse under the menu. You should press the little arrow beside these green buttons in order to choose among: Robocode, RoboRumble, TeamRumble, and MeleeRumble. The 3 last ones are for running the RoboRumble@Home clients.

How to run the unit tests?

When you want to run the unit test from within Eclipse, you must do this from the the Package Explorer, where you right-click on the 'robocode.tests' project and select 'Run As' -> 'JUnit Test'. Now all available unit tests will run automatically.

Alternatively you can start the tests from the command-line by standing on your robocode workspace, and write the following Maven command.

On Windows:

 mvn test install

On Linux:

 ./mvn.sh test install

Robocode developers and contributions

Robocode developers have discussion group at robocode-developers@googlegroups.com. Everybody interested in discussion about future of Robocode are welcome. We also welcome your contributions there. The discussion group is located here: http://groups.google.com/group/robocode-developers.

See also

• Old version of the Developer's Guide for building Robocode for Robocode versions prior to version 1.7.
• Browse the sources of Robocode.
• Download the sources of Robocode.
• Robocode developers discussion group.

References

• The Robocode project on SourceForge.
• How to access the SVN Repository for Robocode.
• Eclipse - an open development platform supported by Robocode.
• Apache Maven used for building Robocode.
• Guide to using Eclipse with Maven 2.x.
• Eclipse Subversive is a plugin used for accessing Subversion from Eclipse.
• Subclipse is also a plugin used for accessing Subversion from Eclipse.
• TortoiseSVN, a Subversion client for Windows.
• CollabNets Subversion, a Subversion client for both Windows and Linux.