Robocode/Developers Guide for building Robocode
This guide describes how to build the Robocode game using Eclipse.
This guide is valid from Robocode version 1.7. If you want to build older versions of Robocode you must use the old version of the developer's guide available here.
Contents
Developer's Guide for building Robocode using Eclipse
Notice
This guide is intended for experienced Java developers who want to work on the Robocode game itself. This guide describes all the basic stuff in order to compile and run Robocode using the Eclipse IDE.
If you just want to browse the sources, you can do it here or you can download the zipped sources from here.
Introduction
All sources of Robocode are available in the Subversion (SVN) Repository on SourceForge (SF) for the Robocode project, and you can read about how to access the SVN Repository for Robocode here. Subversion 1.5 is the Version Control System (VCS) used for Robocode.
Basically, all you need is the sources of Robocode (which can be downloaded as a .zip file or downloaded from the Subversion repository) and Maven installed. Maven is being used in order to build everything in the Robocode project. However, if you want to work with the sources of Robocode, you might of course want to use an IDE for compiling and run Robocode on the fly to see the effect of your work.
Batch files and Shell scripts are provided for building Robocode under Windows and Linux (including and Mac OS X). These scripts have been developed for Windows XP/Vista and Ubuntu 8.10 (Linux).
What skills do you need?
- Eclipse (Eclipse tutorial)
- Subversion (Subversion book)
- Maven (Maven in 5 Minutes)
This guide is focusing on how to build and run Robocode using the Eclipse, which is supported by Robocode. Eclipse is a very popular IDE that comes free of charge, and which supports SVN access to the sources, a rich source code editor, automatic compilation etc.
This guide assumes that you have some basic knowledge about how to download, install and use Eclipse. Hence, this guide will not teach you how to use Eclipse, but rather focuson how to build Robocode within Eclipse. The same applies to other tools used for building Robocode. That is, Subversion (SVN) and Maven.
Please notice that you do not have to be an expert in Eclipse, Subversion, and Maven, but at least some basic knowledge about these. In fact, trying to build Robocode might actually be a very good way of learning these tools.
You don't have to worry too much of how to setup Eclipse for building Robocode as the sources of Robocode contains all configuration files that Eclipse needs. Some of these files can and is generated using Maven's build-in support for Eclipse. However, you still 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 might need to update the sources from SVN once in a while and merge these with your changes in order to keep up to date with the current versions of Robocode, at least if you work on the trunk/head branch of the Robocode sources.
Software Requirements
Required:
- Sun JDK 5.0 (download).
- Eclipse Classic 3.4.1 or newer (download).
- A Subversion client like TortoiseSVN 1.5.7 or newer (download) (for Windows) ... or CollabNet Subversion Command-Line Client v1.5.5 (download) for Windows and Linux.
Highly Recommended:
- Eclipse Subversive 0.7.3 or newer (installation procedure described later) or Subclipse 1.4.7 or newer (installation procedure is not described in this guide).
Install Sun JDK 5.0
First you must ensure that the Sun JDK 5.0 is available on your system. If not, you need to install Sun JDK 5.0 before installing Eclipse, which requires a JDK. Please notice that you must install the JDK (Java Developer Kit), and not just the JRE (Java Runtime Environment) as the JRE is insufficient when building Robocode.
It is important that the Java vendor is Sun in order to guarantee that you'll not run into some unexpected problems when using the Java compiler etc. Most problems caused by building Robocode (and when compiling robots for Robocode) is caused by Java versions from other vendors than Sun.
Also make sure that you use version 5.0 of the JDK, not a never version like e.g. the JDK 6. Otherwise you might experience problems when building Robocode, and if you distribute your version of Robocode, your version will require Java 6 in order to run properly. Currently, Robocode must be able to run under Java 5.0.
When installing the JDK, I recommend that you install the sources for Java as these are very useful when debugging you sources when working on Robocode. However, it is not a requirement to install the Java sources provided with the JDK.
Set the Environment Settings for Java
You must set up the environment variable named JAVA_HOME in your system environment, e.g. JAVA_HOME="C:\Program Files\Java\jdk1.5.0_16"
(on Windows), and JAVA_HOME="/usr/local/Java/jdk1.5.0_16"
(on Linux). In addition, you must add JAVA_HOME\bin (on Windows) to your PATH environment variable, e.g. PATH=%PATH%;JAVA_HOME\bin
(on Windows), and PATH=$PATH:$JAVA_HOME/bin
(on Linux). This must be done as Maven (used for building Robocode) is depending on the JAVA_HOME environment variable, and must know where to locate the Sun JDK 1.5.
If you want more information of how to setup your JAVA_HOME and PATH environment variables for your specific OS, please read the installation notes provided for the Sun JDK 5.0 here.
Install Eclipse
When the Sun JDK 5.0 is avaiable on your system, you must install the Eclipse 3.4 if it is not available on your system already. Please notice, that older versions of Eclipse (like e.g. Eclipse 3.2 provided with Ubuntu 8.10) will not work with the setup used in this guideline. Consult the installation notes provided for Eclipse in order to find out how to install Eclipse 3.4 on your specific OS.
Create a workspace for Robocode
The first time you start up 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 created a workspace, e.g. the one that Eclipse propose as default, the first time Eclipse is started it, you can create a new workspace if you wish by selecting File -> Switch Workspace -> Other... from the menu.
Use Subversive or Subclipse
The next step (which is optional) is to install Subversive or Subclipse into Eclipse in order to get direct access to the sources of Robocode in the SVN repository. Notice, you'll only have read access to the sources. Also notice, that you don't have to install the Subversive or Subclipse as long as you use another Subversion client. However, it makes life easier when you work within Eclipse.
I recommend you to use Subversive that has proven to be very stable within Eclipse 3.4.1. In the following you can read how to install Subversive into Eclipse.
How to install Subversive
In order to install Subversive into Eclipse, you can choose between using the Update Site or Archived Update Site. You can get more information here. You'll need to install:
- Subversive SVN Team Provider Plugin 0.7.3 or newer.
- SVNKit 1.2.0 or newer, which is a Subversive SVN Connector. At least one Subversive SVN Connector is required. Note that you might gain speed by using another SVN Connector like e.g. the Native JavaHL 1.5.0 or never.
In the following, we will use the Update Site for installing Subversive:
- In Eclipse you must select 'Help' -> 'Software Updates... from the menu.
- Then you select the 'Available Software' tab
- Press the 'Add Site...' button, and enter http://download.eclipse.org/technology/subversive/0.7/update-site/ into the text field and press OK or enter. Notice, that this update site might change, so might have to get the updated URL to the Update Site from here.
- Unfold the site you just added and put a checkmark in the 'Subversive SVN Team Provider Plugin'.
- Again, press the 'Add Site...' button, and enter http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/ into the text field and press OK or enter. Notice, that this update site might change, so might have to get the updated URL to the Update Site from here.
- Unfold the site you just added and put a checkmark in the 'SVNKit 1.2.0' or 'JavaHL 1.5.0' (or never versions) under the 'Subversive SVN Connectors' tree (you can also use a newer version of the SVN Connector of course).
- Press 'Install' and follow the instruction given by Eclipse to install the plugins. It will ask if you wish to restart Eclipse, and I recommend you to answer 'yes' in order to restart Eclipse.
- Now, Subversive is ready to be used.
Setup the Robocode workspace step by step
In the following steps I assume that you now have the JDK, Eclipse, TortoiseSVN or CollabNet Subversion, and Subversive or Subversion up and running. I also assume that the current workspace is set to Robocode workspace; otherwise you should change it to your Robocode workspace. The following steps describes how to setup your workspace for Robocode and how to extract the Robocode sources from the SVN (Subversion).
Checkout sources from the SVN
Remember the workspace you created for Eclipse in an earlier step? Now, you should navigate into this root folder from your desktop, i.e. not from a command prompt or shell. From within the root folder of your robocode workspace you right-click and select 'SVN Checkout'. A window will pop up, and now you must enter the branch of Robocode you want to work on. That would typically be the trunk or head of the sources, which is the main branch containining the newest sources of Robocode. However, you might also want to check of a specific version of Robocode or some other branch available.
If you want to checkout the sources for the trunk/head, you must use this URL:
https://robocode.svn.sourceforge.net/svnroot/robocode/robocode/trunk
If you instead want to checkout the sources for a specific Robocode version, you must use this URL:
https://robocode.svn.sourceforge.net/svnroot/robocode/robocode/tags/VER_X_X_X
..where X_X_X must be replaced with a real version number, e.g. '1_5_3' for version 1.5.3
When you have entered or copy-and-pasted the URL into the checkout window you press OK. Now all the sources of the selected branch will be checked out from the SVN.
Preparing command-line tools
In order to make it build Robocode, batch files / shell scripts have been provided to make trivial tasks easier. For example, you don't need to install tools like Maven, Ant, JUnit, Jacobe yourself. You just run 'loadTools' from the command-line, and it will download required files from the Robocode site so you are able to use these tools from script files.
Hence, you must run the 'loadTools' script from the command line. From a command-promt or shell you must go into the root folder of your robocode workspace. Next you run the loadTools script.
On Windows:
cd tools
loadTools
On Linux:
cd ./tools
./loadTools.sh
Preparing your workspace for Eclipse
Next we must prepare your workspace for Eclipse. Eclipse needs the project files, class files, and other configuration files in order order to let you view, edit, and compile Robocode. Maven provides support for using Eclipse with Maven. You can read more about this here:
I highly recommend you to read this in order to understand how Eclipse and Maven works together.
First, we need to create all the required Eclipse files, which we do with another Maven command.
On Windows:
mvn eclipse:eclipse
On Linux:
./mvn.sh eclipse:eclipse
Next, you should compile the sources of Robocode in order to have your local Maven repository created and prepared for later.
On Windows:
mvn compile
On Linux:
./mvn.sh compile
Now your Robocode workspace is ready almost ready. You just need to import all the projects into your Eclipse workspace. You do this by starting up Eclipse with your Robocode workspace. From the menu bar you select 'File' -> 'Import...' -> 'Existing Projects into Workspace'. Now select the root directory to be the root path of your Robocode workspace. You should see a list of Robocode project. When you do, you must press 'Finish'.
The last thing you need to do is to set up the M2_REPO class path variable for Eclipse, so Eclipse knows where to locate the Maven repository. When building Robocode using Maven, Maven will download all required classes from other sites into this local Maven repository. Hence, Eclipse needs to know the class path for this Maven repository in order to compile all the sources of Robocode. So you 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 (~).
In Eclipse, you 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
or /home/fnl/.m2/repository
.
When Eclipse ask you if you want to rebuild the workspace, you select 'Yes' in order to rebuild everything so you are ready to work on Robocode.
How to start Robocode in Eclipse?
When all sources builds without errors (warnings are expected), you are able to launch Robocode. You do this by selecting 'Run' -> 'Run Configurations...' from th Menu. On the window that shows up, you expand the 'Java Applications', select 'Robocode', and press the 'Run' button.
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
On Linux:
./mvn.sh test
How to build the 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 start the following batch/shell file wrong the command-line within the robocode workspace directoty.
On Windows:
mvnassembly
On Linux:
./mvnassembly
This will build the distribution files, which will be put into the sub-directory named target.
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 Bubversion, a Subversion client for both Windows and Linux.