View source for Robocode/Old Developers Guide for building Robocode

This guide describes how to build the Robocode game using [http://www.eclipse.org 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 [[Robocode/Old Developers Guide for building Robocode|here]].

== Developer's Guide for building Robocode using Eclipse ==

=== Obsolete ===
'''Guide below on this page is for building Robocode before version 1.7.4.2'''. The current version of this guide can be found at [[Robocode/Developers Guide for building Robocode]].

=== 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 [http://code.google.com/p/robocode/source/browse/ here] or you can download the zipped sources from [http://sourceforge.net/project/showfiles.php?group_id=37202&package_id=218677 here].

=== Introduction ===

All sources of Robocode are available in the [http://code.google.com/p/robocode/source/browse/ SVN Repository] for the [http://sourceforge.net/projects/robocode Robocode project] on SourceForge (SF). You can read about how to access the SVN Repository for Robocode [http://code.google.com/p/robocode/source/checkout here]. Subversion (SVN) 1.5 is being used as the Version Control System 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 [http://maven.apache.org/ 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 Mac OS X). These scripts have been developed for Windows XP/Vista and Ubuntu 8.10 (Linux). Please notice that the Linux setup should also work for e.g. Solaris, FreeBSD etc.

=== What skills do you need? ===

* Eclipse ([https://eclipse-tutorial.dev.java.net/ Eclipse tutorial])
* Subversion ([http://svnbook.red-bean.com/ Subversion book])
* Maven ([http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven in 5 Minutes])

This guide is focusing on how to build and run Robocode using the [http://www.eclipse.org/ 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, has a big supporting community, lot's of plugins, and much much more.

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 focus on how to build Robocode within Eclipse. The same applies to other tools used within this guide.

Please notice that you do not have to be an expert in Eclipse, Subversion, and Maven. But you need some basic knowledge about these in order 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.

You don't have to worry too much about how to setup Eclipse for Robocode as the provided sources in SVN contains all configuration files needed by Eclipse. Some of these files are 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 will need to update the sources from SVN once in a while and merge these with your local 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 ([http://java.sun.com/javase/downloads/index_jdk5.jsp download]).
* Eclipse Classic 3.4.1 or newer ([http://www.eclipse.org/downloads/ download]).
* A Subversion client like TortoiseSVN 1.5.7 or newer ([http://tortoisesvn.net/downloads download]) (for Windows) ... or CollabNet Subversion Command-Line Client v1.5.5 ([http://www.collab.net/downloads/subversion/ download]) for Windows and Linux.

'''Highly Recommended:'''
* [http://www.eclipse.org/subversive/ Eclipse Subversive] 0.7.3 or newer (installation procedure described later) or [http://subclipse.tigris.org/ 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 for 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 another vendor 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'll not be able to build the sources of Robocode - at least not without fixing all the compiler errors due to the switch from Java 5.0 into Java 6.

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

==== Set the Environment Settings for Java ====

You must set up the environment variable named '''JAVA_HOME''' in your system environment, e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.5.0_16"</code> (on Windows) or <code>JAVA_HOME="/usr/local/Java/jdk1.5.0_16"</code> (on Linux). In addition, you must add JAVA_HOME\bin (on Windows) to your '''PATH''' environment variable, e.g. <code>PATH=%PATH%;%JAVA_HOME%\bin</code> (on Windows), and <code>PATH=$PATH:$JAVA_HOME/bin</code> (on Linux). This must be done as Maven is depending on the JAVA_HOME environment variable, and must know where to locate the JDK.

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:'''
* [http://java.sun.com/j2se/1.5.0/install.html Java Platform Installation]: Find installation notes for Windows, Linux, and Solaris.
* [http://java.sun.com/j2se/1.5.0/system-configurations.html Supported System Configurations]: Find the installation notes for ''all'' supported systems.

==== Install Eclipse ====

When the Sun JDK 5.0 is ready 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 for 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. <code>C:</code> (on Windows) or <code>~</code> (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.

==== Use Subversive or Subclipse ====

The next step (which is optional) is to install [http://www.eclipse.org/subversive/ Subversive] or [http://subclipse.tigris.org/ 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 [http://www.polarion.com/products/svn/subversive.php?src=eclipseproject 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 [http://www.polarion.com/products/svn/subversive.php?src=eclipseproject 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 [http://www.polarion.com/products/svn/subversive.php?src=eclipseproject 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:
  http://robocode.googlecode.com/svn/robocode/trunk/

If you instead want to checkout the sources for a specific Robocode version, you must use this URL:
  http://robocode.googlecode.com/svn/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:

* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide to using Eclipse with Maven 2.x]

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'.

==== M2_REPO class path variable ====

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. <code>H:/Users/Flemming/.m2/repository</code> or <code>/home/fnl/.m2/repository</code>.

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.

If you need to start other parts of Robocode like e.g. RoboRumble, you need to create a launch configuration for it, in order to be able to launch it. You can read more about how to create your own launch configurations in Eclipse in this [http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/tasks-java-local-configuration.htm guide]. This guide is also helpful if you want to modify the Robocode.launch configuration available for launching the Robocode game.

==== 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

==== 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.sh

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

=== 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 ==
* [[Robocode/Old Developers Guide for building Robocode|Old version]] of the Developer's Guide for building Robocode for Robocode versions prior to version 1.7.
* [http://code.google.com/p/robocode/source/browse/ Browse the sources] of Robocode.
* [http://sourceforge.net/project/showfiles.php?group_id=37202&package_id=218677 Download the sources] of Robocode.
* [http://groups.google.com/group/robocode-developers Robocode developers discussion group].

== References ==
* The [http://sourceforge.net/projects/robocode Robocode project] on SourceForge.
* [http://sourceforge.net/svn/?group_id=37202 How to access] the SVN Repository for Robocode.
* [http://www.eclipse.org/ Eclipse] - an open development platform supported by Robocode.
* [http://maven.apache.org/ Apache Maven] used for building Robocode.
* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide] to using Eclipse with Maven 2.x.
* [http://www.eclipse.org/subversive/ Eclipse Subversive] is a plugin used for accessing Subversion from Eclipse.
* [http://subclipse.tigris.org/ Subclipse] is also a plugin used for accessing Subversion from Eclipse.
* [http://tortoisesvn.net TortoiseSVN], a Subversion client for Windows.
* [http://www.open.collab.net/downloads/subversion/ CollabNets Subversion], a Subversion client for both Windows and Linux.

[[Category:Robocode Documentation]]
[[Category:Eclipse IDE]]