Difference between revisions of "Robocode/Developers Guide for building Robocode"

From Robowiki
Jump to navigation Jump to search
(New Developers Guide for building Robocode for Git)
Line 1: Line 1:
−
This guide describes how to build the Robocode game using [http://www.eclipse.org Eclipse].
+
This guide describes how to build Robocode using [http://git-scm.com/ Git], [http://maven.apache.org Maven] and [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]].
+
This guide applies for Robocode version 1.7.4.2 and newer.
  
−
== Developer's Guide for building Robocode using Eclipse ==
+
== Developer's Guide for building Robocode with Eclipse setup ==
  
 
=== Notice ===
 
=== 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.
+
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 [http://www.eclipse.org 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].
+
If you just want to browse the sources, you can do it from [https://github.com/robo-code/robocode here] or you can download the zipped sources from [http://sourceforge.net/projects/robocode/files/robocode%20sources/ here].
  
 
=== Introduction ===
 
=== 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 to get started with building Robocode is:
  
−
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.
+
* Java Developer Kit (JDK) 5.0 or newer ([http://www.oracle.com/technetwork/java/javase/downloads/index.html])
 +
* The source files of Robocode ([https://github.com/robo-code/robocode])
 +
* An Internet connection.
  
−
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.
+
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.
  
−
=== What skills do you need? ===
+
An Internet connection is required for building Robocode distribution files as the build tool (Maven) needs access to [http://maven.apache.org/guides/introduction/introduction-to-repositories.html remote repositories], which contains various libraries and binaries. Some libraries are used for building Robocode, and other 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.
  
−
* Eclipse ([https://eclipse-tutorial.dev.java.net/ Eclipse tutorial])
+
==== Install JDK ====
−
* 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.
+
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.
 +
You do not need to use the obsolete JDK 5.0, but the JDK 5.0 is used for the building official releases for Robocode as Java 5.0 is the minimum requirement for running Robocode. 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 [http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-javase5-419410.html#jdk-1.5.0_22-oth-JPR 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.
  
−
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.
+
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.
  
−
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.
+
==== Set up Java Environment Settings ====
  
−
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.
+
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 to use. PATH is extended in order to locate the Java commands like 'java', 'javac' and lots of other tools in the JDK. This is 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 <code>java -version</code> in the command-line/shell, and detirmine which Java compiler that is being used by writting <code>javac -version</code> instead.
  
−
=== Software Requirements ===
+
'''Windows:'''
 +
* JAVA_HOME is set to e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.5.0_16"</code>.
 +
* PATH is extended, e.g. to <code>PATH=%JAVA_HOME%\bin;PATH</code>.
  
−
'''Required:'''
+
'''Linux / *nix:'''
−
* Sun JDK 5.0 ([http://java.sun.com/javase/downloads/index_jdk5.jsp download]).
+
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.5.0_07/bin/java</code>. (Bash)
−
* Eclipse Classic 3.4.1 or newer ([http://www.eclipse.org/downloads/ download]).
+
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)
−
* 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:'''
+
'''Mac OS X:'''
−
* [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).
+
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=$(/usr/libexec/java_home)</code>.
 +
* PATH is extended, e.g. by <code>export PATH=${JAVA_HOME}/bin:$PATH</code>.
  
−
==== Install Sun JDK 5.0 ====
+
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:
  
−
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.
+
'''Installation Notes from Sun:'''
 +
* [http://www.oracle.com/technetwork/java/javase/index-137561.html Installation Notes] for Windows, Linux, Solaris, and Mac.
 +
* [http://www.oracle.com/technetwork/java/javase/system-configurations-135212.html Certified System Configurations for Java] for ''all'' supported systems.
  
−
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.
+
==== Required technical skills? ====
  
−
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.
+
In order to develop on Robocode, you need to know the basics of these tools:
  
−
==== Set the Environment Settings for Java ====
+
* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html])
 +
* Git and GitHub ([http://www.vogella.com/articles/Git/article.html])
 +
* Maven ([http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven in 5 Minutes])
  
−
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.
+
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. :-)
  
−
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:
+
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 [http://www.eclipse.org 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. :-)
  
−
'''Installation Notes from Sun:'''
+
All sources of Robocode are available at [https://github.com/robo-code/robocode GitHub]. At GitHub, you can download sources as a zipped file or create your own [https://help.github.com/articles/fork-a-repo clone/fork], if you want to.
−
* [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 ====
+
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.
  
−
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.
+
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.
  
−
==== Create a workspace for Robocode ====
+
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.
  
−
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.
+
=== Checking out sources from GitHub ===
  
−
==== Use Subversive or Subclipse ====
+
In the following, I assume that you want to ''check out'' the sources from GitHub using some [http://git-scm.com/downloads Git client].  This could be one of the Git GUI Clients (''git-gui'') recommended [http://git-scm.com/downloads/guis 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 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.
+
The URL of the sources at GitHub is:
 +
[https://github.com/robo-code/robocode.git https://github.com/robo-code/robocode.git]
  
−
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 build distribution files? ====
  
−
==== How to install Subversive ====
+
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 call the '''mvnassembly''' script from the command-line when standing within the root directory of the Robocode sources.
  
−
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:
+
On Windows:
 +
  mvnassembly
  
−
* Subversive SVN Team Provider Plugin 0.7.3 or newer.
+
On *nix:
−
* 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.
+
  ./mvnassembly.sh
  
−
In the following, we will use the Update Site for installing Subversive:
+
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 plugins etc. used for building Robocode. So please be patient with it the first time.
  
−
# In Eclipse you must select 'Help' -> 'Software Updates...'' from the menu.
+
=== Setting up Eclipse for developing on Robocode ===
−
# 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 ===
+
Here follows a description of how to setup Eclipse for developing on Robocode.
  
−
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).
+
==== Software Requirements for Eclipse IDE ====
  
−
==== Checkout sources from the SVN ====
+
Here follows the recommended software needed to start developing on Robocode with the Eclipse IDE:
  
−
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.
+
'''Required:'''
 +
* Java 6 JRE/JDK or newer ([http://www.oracle.com/technetwork/java/javase/downloads/index.html download])
 +
* Eclipse Classic 4.2 (Juno) or newer ([http://www.eclipse.org/downloads/ download]). An older version of Eclipse, e.g. Eclipse 3.7 should also be sufficient.
  
−
If you want to checkout the sources for the trunk/head, you must use this URL:
+
'''Highly Recommended:'''
−
  http://robocode.googlecode.com/svn/robocode/trunk/
+
* [http://eclipse.github.com/ GitHub for Eclipse] named [http://www.eclipse.org/egit/ EGit] 2.0.0, which is a Eclipse plug-in (installation procedure is described later).
  
−
If you instead want to checkout the sources for a specific Robocode version, you must use this URL:
+
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 [http://www.eclipse.org/eclipse/development/readme_eclipse_4.2.html#TargetOperatingEnvironments tested] with Java 6 and Java 7.
−
  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.
+
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.
  
−
==== Preparing command-line tools ====
+
Please consult the [http://wiki.eclipse.org/Eclipse/Installation#Install_a_JVM installation notes] provided for Eclipse in order to find out how to install Eclipse for your specific OS.
  
−
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.
+
==== Create a workspace for Robocode ====
  
−
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.
+
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.
  
−
On Windows:
+
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. <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.
−
  cd tools
 
−
  loadTools
 
  
−
On Linux:
+
==== M2_REPO class path variable ====
−
  cd ./tools
 
−
  ./loadTools.sh
 
  
−
==== Preparing your workspace for Eclipse ====
+
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.
  
−
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:
+
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 (~).
  
−
* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide to using Eclipse with Maven 2.x]
+
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. <code>H:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (Linux).
  
−
I highly recommend you to read this in order to understand how Eclipse and Maven works together.
+
If or when Eclipse ask you if you want to rebuild the workspace, you select 'Yes'.
  
−
First, we need to create all the required Eclipse files, which we do with another Maven command.
+
==== Configure JRE/JDK for your workspace ====
  
−
On Windows:
+
You must setup which JRE/JDK that will be used for compiling (and running) Robocode in your workspace.
−
  mvn eclipse:eclipse
+
You do this by...
 +
# selecting Window -> Preferences from the menu, and then unfold and select Java -> Installed JREs and press 'Add...' on the 'Installed JREs' page.
 +
# Select 'Standard VM' on the 'JRE Type' page and press 'Next >' or Enter.
 +
# 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.
 +
# 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.
  
−
On Linux:
+
==== Using EGit for accessing the sources on GitHub ====
−
  ./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.
+
The next step (which is optional) is to install [http://www.eclipse.org/egit/ 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 ====
  
−
On Windows:
+
A description of how to install EGit into Eclipse is provided [http://www.eclipse.org/egit/download/ here]. But if you are not familiar with how it is done, a description is follows here:
−
  mvn compile
 
  
−
On Linux:
+
# In Eclipse you must select 'Help' -> 'Intall New Software...' from the menu.
−
  ./mvn.sh compile
+
# 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 [http://www.eclipse.org/egit/download/ here] and use the one that is recommended.
 +
# Now, unfold the 'Eclipse EGit Team Provider' that appears in the list below the update site you just entered.
 +
# Put a checkmark into you just added and put a checkmark for the 'Eclipse EGit' and press the 'Next' button.
 +
# 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.
 +
# When Eclipse has been restarted, EGit will be ready to be used in Eclipse.
  
−
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'.
+
==== Importing sources of Robocode using EGit ====
  
−
==== M2_REPO class path variable ====
+
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...
  
−
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 (~).
+
# Right-click the mouse and select 'Import...' in the popup menu that occurs.
 +
# Unfold 'Git' in the 'Import' window and double-click 'Projects from Git'.
 +
# On the 'Import Projects from Git' you select 'URI'.
 +
# 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 >'.
 +
# 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.
 +
# 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.
 +
# On the 'Select a wizard to use for importing projects', make sure 'Import existing projects' is selected and press 'Next >' or Enter.
 +
# 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.
 +
# All Robocode projects will now be imported into Eclipse and be visible in the Package Explorer.
 +
# 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.
  
−
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>.
+
Congratulations, you should now be able to get started working on the Robocode sources in Eclipse. :-)
  
−
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.
+
==== Launch Robocode ====
  
−
==== How to start Robocode in Eclipse? ====
+
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.
  
−
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.
+
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'.
  
−
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.
+
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? ====
 
==== How to run the unit tests? ====
Line 175: Line 194:
 
On Linux:
 
On Linux:
 
   ./mvn.sh test install
 
   ./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 and contributions ===

Revision as of 23:02, 18 September 2012

This guide describes how to build Robocode using Git, Maven and Eclipse.

This guide applies for Robocode version 1.7.4.2 and newer.

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 ([1])
  • The source files of Robocode ([2])
  • 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 other 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. You do not need to use the obsolete JDK 5.0, but the JDK 5.0 is used for the building official releases for Robocode as Java 5.0 is the minimum requirement for running Robocode. 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 Settings

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 to use. PATH is extended in order to locate the Java commands like 'java', 'javac' and lots of other tools in the JDK. This is 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:

Required technical skills?

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

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

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 (~).

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

If or when Eclipse ask you if you want to 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

References

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