Robocode/Developers Guide for building Robocode

This guide describes how to build Robocode using Git, Maven and Eclipse and applies for Robocode version 1.7.4.2 and newer, which has been moved to GitHub.

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 game itself, and describes all basic stuff required to compile and run Robocode within the Eclipse IDE.

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

Introduction

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

• Java Developer Kit (JDK) 5.0 or newer (downloads)
• The source files of Robocode (on GitHub)
• 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 that requires lots of time to understand and master its internal design.

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.

Install JDK

Robocode is being developed in Java SE, and requires the Java Developer Kit (JDK) 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 5.0 is used for the building official releases for Robocode as Java 5.0 is the minimum requirement for running Robocode. However, you do not need to use the obsolete JDK 5.0, if you don't want to. But compiling Robocode with the JDK 5.0 guarantees that Robocode will be able to run on Java 5.0. You can get the old Java 5.0 from here.

If you just want to play with the sources, you could use a newer JDK without any trouble. 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. Also note that the Sun/Oracle version of the JDK is preferable for building Robocode.

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.

Set 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.5.0_16".
• 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.5.0_07/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 Sun JDK 5.0 here:

Installation Notes from Sun:

• 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:

• Java 6 JRE/JDK or newer (download)
• Eclipse Classic 4.2 (Juno) or newer (download). An older version of Eclipse, e.g. Eclipse 3.7 should also be sufficient.

Highly Recommended:

• GitHub for Eclipse named EGit 2.0.0, which is a Eclipse plug-in (installation procedure is described later).

In order to run the Eclipse IDE, a Java 6 JRE or JDK should is required/recommended. That is, the Juno release of Eclipse has been tested with Java 6 and Java 7.

The version numbers just provided here are as a kind of guarantee that these will work with the present version of Robocode (1.7.4.2) and counts for reference for this guide.

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. H:/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 JRE/JDK for your workspace

You must setup which JRE/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 5 or 6 (JDK 5 is preferable when developing on Robocode) and press 'Finish' or Enter. Make sure to select a JDK and not just a JRE.
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.

Using EGit for accessing the sources on GitHub

The next step (which is optional) is to install Egit into Eclipse in order to get direct access to the sources of Robocode in the GitHub repository. Notice, you'll only have read access to the sources, but could make your own Git repository if you wish to. Also notice, that you don't need to install EGit in Eclipse in order to work with the sources, as you could simply copy and import the Robocode sources into your workspace. However, it makes life easier using EGit, as you will be able to get changes made to Robocode and merge this into your local sources.

Install EGit into Eclipse

A description of how to install EGit into Eclipse is provided here. But if you are not familiar with how it is done, a description is follows here:

1. In Eclipse you must select 'Help' -> 'Intall New Software...' from the menu.
2. Enter http://download.eclipse.org/egit/updates/ into the 'Work with:' text field and press the 'Add' button or the enter key. Notice, that this update site might change, so you might have to get the updated URL from here and use the one that is recommended.
3. Now, unfold the 'Eclipse EGit Team Provider' that appears in the list below the update site you just entered.
4. Put a checkmark into you just added and put a checkmark for the 'Eclipse EGit' and press the 'Next' button.
5. Press 'Finish' on the window that follows and follow the instructions given by Eclipse to install this plugin. It will ask if you wish to restart Eclipse, and I recommend you to answer 'yes' in order to restart Eclipse.
6. When Eclipse has been restarted, EGit will be ready to be used in Eclipse.

Importing sources of Robocode using EGit

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 EGit (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.