Robocode/Older Developers Guide for building Robocode

From Robowiki
< Robocode
Revision as of 13:39, 25 February 2009 by Nat (talk | contribs) (freplace extenal like by normal link)
Jump to navigation Jump to search

This guide describes how to build the Robocode game using the Eclipse IDE.

Developer's Guide for building Robocode using Eclipse

Obsolete

Guide below on this page is for building Robocode before version 1.7. Robocode/Developers Guide for building Robocode Actual version of guide could be found here]

Introduction

This guide is meant for developers who want to compile and build Robocode application. If you just want to browse the sources, you can do it here or you can download the zipped sources from here.

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.

Basically, you only need the sources of Robocode and then run an Ant build script provided with the sources (assuming that you have Apache Ant installed) in order to build Robocode. This way you'll be able to build the distribution files for Robocode. However, if you want to do your own experiments with the sources or make your own personal version 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.

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, which is free of charge, and which support accessing the sources directly on the versioning control system, supports Ant build scripts, a very good source editor, automatic compilation etc. In this guide I assume you have some basic knowledge about how to use Eclipse, and this guide will not teach you how to use Eclipse.

If you choose to use Eclipse for building Robocode, you don't have to worry too much of how to setup the IDE for building Robocode, as the sources of Robocode contains most of the configuration files needed for Eclipse. But you still need to do some basic pre-configuration of Eclipse before you'll be able to check out and build Robocode. You should only need to setup a workspace for Robocode once, and then you should be able to concentrate on working on the Robocode sources and perhaps merge your files with new source versions (when Robocode is updated) that occurs on the versioning control system for Robocode.

Software Requirements

  • Sun's Java SE JDK 5.0 (download)
  • Eclipse IDE for Java Developers or Eclipse Classic 3.4 (Ganymede) (download) or Eclipse SDK 3.4 (download).
  • Eclipse Subversive 0.7.2 or newer (installation procedure described later)

You must install the Java JDK before installing the Eclipse IDE, as it requires Java. Also notice that you must install the JDK (Java Developer Kit), and not just the JRE (Java Runtime Environment) as the JRE is not sufficient when building Robocode.

When installing the JDK, I recommend that you install the sources for Java as these are very useful when debugging your Java code, and hence also when debugging Robocode. But it is not a requirement to install the Java sources available with the JDK.

You must ensure that you have set up the environment variable named JAVA_HOME, 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 Unix, Linux, and Mac OS X). In addition, you must add JAVA_HOME/bin to your PATH environment variable, e.g. PATH=%PATH%;JAVA_HOME\bin (on Windows), and PATH=$PATH:$JAVA_HOME/bin (on Unix, Linux, and Mac OS X). This must be done as the Apache Ant build tool (used for building Robocode) is depending on these environment variables, and will not be able to build Robocode without them. If you have problem with setting up JAVA_HOME and PATH, you should search for how to setup these for your specific OS on the web.

You need to install the Eclipse Subversive into Eclipse in order to access the sources from Robocode's Subversion (SVN) Repository. You could also use Subclipse, which is easier to install. However, it makes Eclipse 3.4 unstable (at least on my system), and Subversive is and "official" eclipse.org project. It means that Subversive has all project infrastructure at eclipse.org, project plan is synchronized with Eclipse development (read more about it here. Therefore I recommend you to use Subversive instead of Subclipse.

Create a workspace for Robocode

At this point I assume that you have sucessfully installed the Java SDK and Eclipse.

The first time you start up Eclipse, it will ask for a folder for your workspace. I suggest that you create a workspace named robocode-workspace or similar at put it on a partition (e.g. on C: on Windows) or any other folder 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 one if you wish by selecting the File -> Switch Workspace -> Other... from the menu.

Installation of Subversive

The next step is to install the Subversive into Eclipse. Here I assume that you have installed Eclipse 3.4 (Ganymede).

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.

In the following, we will use the Update Site for installing Subversive.

  1. In Eclipse you must select Help -> Software Updates... from the menu.
  2. Then you select the 'Available Software' tab
  3. 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.
    1. Unfold the site you just added and put a checkmark in the 'Subversive SVN Team Provider Plugin'.
  4. 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.
    1. Unfold the site you just added and put a checkmark in the 'SVNKit 1.2.0' (or JavaHL 1.5.0) under the 'Subversive SVN Connectors' tree (you can also use a newer version of the SVN Connector of course).
  5. 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.
  6. Now, Subversive is ready to be used.

Setup the Robocode workspace step by step

In the following steps I assume that you have Java, Eclipse, and Subversive 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).

Add JRE 5.0

First you need to add the Java SE 5.0 Runtime Environment (JRE) to your new workspace. The JRE is included with the JDK.

  1. Go to the Window menu and select 'Preferences....
  2. Locate the 'Installed JREs' under the 'Java' node in the left side of the Preferences window. You will have to unfold the 'Java' tree in order to find the 'Installed JREs'.
  3. Check if the JRE for Java 5.0 is listed under 'Installed JREs'. It should be listed as e.g. jdk1.5.0_xx. If so, you don't need to add the JRE 5.0, as it is already added to your workspace, and you can skip the following. If not, click on 'Installed JREs' and press the 'Add...' button on the right side of the window. A 'Add JRE' window is opened where you:
    1. Double-click on the 'Standard VM' or just press 'Next' if the 'Standard VM' is selected.
    2. On the new window that will appear, you must press the 'Directory...' button on the top right to select the JRE home folder.
    3. On the browse window that now appears, you must browse to and select the folder where you have installed the Java SE JDK 5.0, e.g. something like C:\Program Files\Java\jdk1.5.0_16 (on Windows). Next press the 'OK' button.
    4. If the above step was done correctly, the list of 'JRE System Libraries' etc. is automatically filled out for you.
    5. Now, press "Finish" to close the window.
    6. You will now be back to the first window with the 'Installed JREs', where you must put a checkmark in the jdk1.5.0_xx checkbox.
  4. Press 'OK' to close the Preferences window.

Extract Robocode sources from the SVN

Now we are ready to get the Robocode sources from the official Robocode SVN. Please notice that you'll only have read access. Only members of the Robocode project is able to write to the SVN. The benefit of accessing the SVN is that you'll be able to receive updates made on the SVN. Notice that you'll only get the updates when you run the 'Update' from the 'Team' feature (available in the popup menu, when you select one or several project and right-click the mouse).

  1. In the File menu, hold the mouse over the first item, 'New', and select the last item 'Other...'.
  2. A 'New' window will open, where you must double-click on the 'SVN' item and select 'Projects from SVN', and press the 'Next' button.
  3. A new 'Checkout from SVN' window will open where you must type in one of the following URLs into the 'URL' text field:
  4. Now, click on the 'Advanced' tab, remove the checkmark in the 'Enable Structure Detection', and press the 'Next' button.
  5. A new window with the title 'Checkout from SVN' will show up, where you should be able to see a list of all the available Robocode modules/projects in the SVN Repository from the version or branch you selected in the URL previously. The following modules/projects are:
    • autoextract (optional - the installer of Robocode)
    • build (optional - for building the distribution files)
    • robocode (mandatory - main sources of Robocode)
    • robocodeextract (mandatory - battle files, configuration files, Jikes distribution files, sample robots etc.)
    • roborumble (optional - the RoboRumble@Home client)
    • tools (optional - code beautifying using Jacobe)
    • tests (optional - test units for Robocode)
  6. If you just want to play with the Robocode game itself, you only need to select the mandatory projects 'robocode' and 'robocodeextract'. If you want to make your own distribution files for installing Robocode (with your changes), you also need to select the projects 'autoextract', 'build', and 'roborumble'. The 'tools' and 'tests' projects are used for code beautifying the sources of Robocode and to run test units. Note that you are able to checkout the optional projects later on, when you need them.
  7. A window with the title 'Check Out As' will show up, where you just press the 'Finish' button.
  8. Now Eclipse will look find the projects you selected in the SVN. This will take a while. When Eclipse has found all the selected projects, a new window named 'Check Out Project' will show up will all the projects you have selected. Just press the 'Finish' button, and all the projects will be checked out. This will take a while.

When Eclipse has finished downloading all required sources from the SVN, it should automatically compile the sources for you, and you should be able to run Robocode.

The Robocode launch directory

Eclipse will automatically build and copy all required files into a directory named 'launch' under the project named 'robocode'. The launch directory acts like the installation folder of robocode, and Robocode will put files it needs t store, e.g. configuration files, and you can also put in your own files like you would do with your robocode installation folder, e.g. when you want to put in robot files into the 'robot' directory.

In order to see the launch folder, you might have to open the Navigator in Eclipse. You can open this by selecting Navigate -> Show in -> Navigator from the menu. You might have to do a refresh of the 'robocode' project in order to see the 'launch' folder. You do this by right-clicking the 'robocode' project and select 'Refresh'.

Running Robocode, RoboRumble etc.

In order to run Robocode, RoboRumble etc. the first time, you have to add the launch configurations first for Eclipse. You do this by clicking on the little arrow on the run-button (round green play button with a white arrow) on the toolbar in the top of the Eclipse window. When you press the little arrow on the run-button, you should select 'Organize Favorites...' on the popup menu that occurs.

On the 'Organized Run Favorites' window that occurs you press the 'Add...' button, and select the applications like e.g. 'Robocode', 'Autoextract' (the installer), 'RoboRumble', 'MeleeRumble', or 'TeamRumble', if these are not already listed in the window. Notice that you only have to add the applications, like e.g. 'Robocode', that you want to be able to run. In the 'Organized Run Favorites' you should move the application up to the top (e.g. 'Robocode'), which you want to start per default. When done, you just have to press the run-button from now on, and Robocode (or one of the other application you prefer) should start running.

About the Robocode modules/projects

Robocode contains the following modules:

  • autoextract, which is the Java installer of Robocode used for installing Robocode.
  • build, which contains the main build script for compiling various parts of Robocode, but especially the distribution files for Robocode (setup jar file and zipped sources).
  • robocode, which contains:
    • resources, the resources for the game, e.g. image and icon files, versions file etc.
    • robocode, which is the Java package of Robocode containing all source files of the game.
  • robocodeextract, which contains files beside the game itself like:
    • OS dependent stuff like icon files and batch files
    • Sample robots
    • Template files for creating a robot
    • Template files for battles
    • The Jikes compiler
    • The license file
    • All above mentioned files are necessary when building the setup file for Robocode.
  • roborumble, which contains the RoboRumble@Home client and server source and configuration files.
  • tests, which contains all unit tests used for basic testing of the Robocode game.
  • tools, which contains tools used for developing Robocode. Currently, it contains the configuration files used for code beautifying the Java sources of Robocode.

The 'build' project/module

The 'build' project is special, as it contains a 'build.xml' file for building the distribution files for Robocode using Apache Ant, which is available in Eclipse. In order to build the distribution files, you just have to right-click on the build.xml file and select Run As -> 1 Ant Build, and then the build script will build the distribution files for you. Notice that this requires that the 'autoextract', 'build', 'robocode', 'robocodeextract', and 'roborumble' projects are available in your workspace.

The generated output from the build.xml file is put in a directory named 'build' under the 'build' project, and you must do a refresh on the 'build' project in order to see the 'build' directory and also see all the newly generated files. You do a refresh by right-clicking the 'build' project and select 'Refresh'. Notice, that you might have to delete the 'build' directory under the 'build' project from time to time, as the build scripts generates some files to keep track of which files that needs to be build. In general, it's always a good idea to delete the build/build directory if you want to be 100% sure that everything (the distribution files) are build correctly.

Beside being able to build the distribution files, the build.xml file is also able to build a subset of Robocode defined as targets. You can see all available target by opening an Ant window, which is done my selecting Window -> Show View -> Ant. Now you drag-and-drop the build.xml file into the Ant view, and should be able to see all the targets.

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

How to run the test units for Robocode?

In order to run all the test cases provided for Robocode under the 'tests' project, you first expand the 'tests' project so all its subdirectories become visible. Then you right-click the 'tests' directory (under the 'tests' project) and select Run As -> JUnit Test. Now all test units should start running, and Eclipse will show how many tests that has errors and/or failures. The next time you want to run all the tests, you can run it from the top menu selecting the green "play button", where you can select the 'tests' in the drop-down menu provided on the right side of this button.

You can also run individual test from the JUnit view, where you just right-click the test you want to run and select 'Run'. Notice, that you can also select 'Debug' instead of 'Run', if you want to debug by e.g. single-stepping thru the test case in order to find out where a test case causes a problem.

See also

References

Retrieved from "http://robowiki.net/w/index.php?title=Robocode/Older_Developers_Guide_for_building_Robocode&oldid=4137"