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

From Robowiki
Jump to navigation Jump to search
(23 intermediate revisions by 5 users not shown)
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 the Robocode application, i.e. the game itself, and not how to build bots for Robocode.
  
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 with Eclipse setup ==
  
== Developer's Guide for building Robocode using Eclipse ==
+
=== Notice ===
 +
 
 +
This guide is intended for experienced Java developers, who want to work on the Robocode application, and describes all basic stuff required to compile and run Robocode within the [http://www.eclipse.org Eclipse] IDE.
 +
 
 +
If you just need 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].
  
=== Notice ===
+
=== Requirements ===
  
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.
+
Basically, all you need to get started with building Robocode is:
  
If you just want to browse the sources, you can do it [http://robocode.svn.sourceforge.net/viewvc/robocode/ here] or you can download the zipped sources from [http://sourceforge.net/project/showfiles.php?group_id=37202&package_id=218677 here].
+
* Oracle JDK 8 ([https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java SE Development Kit 8 Downloads]). Note that only version 6, 7, and 8 will work. Newer versions are not supported (yet) and are almost guaranteed to cause building problems.
 +
* Source files for Robocode ([https://github.com/robo-code/robocode on GitHub]), which you get by doing a Git clone.
 +
* An Internet connection.
  
=== Introduction ===
+
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 and requires a big effort to grasp and understand. There is practically no documentation available that describe the internal logic, architecture, game rules, coding conventions etc. So you will probably be on your own when trying to figure out how Robocode it put together.
  
All sources of Robocode are available in the [https://sourceforge.net/svn/?group_id=37202 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://sourceforge.net/svn/?group_id=37202 here]. Subversion (SVN) 1.5 is being used as the Version Control System used for Robocode.
+
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 others are used for running Robocode, and hence need to be put into the distribution files.
 +
In order to get updates to the sources of Robocode when new versions emerge, an Internet connection is also critical to download changed sources and merge the changes with your version of the sources etc.
  
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.
+
Note that all sources of Robocode are for Java 6, meaning that Robocode is able to run on very old Java versions, which is intentional.
  
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.
+
==== Installing the JDK ====
  
=== What skills do you need? ===
+
Robocode is being developed using Oracle's Java SE, and requires the Java Developer Kit ('''JDK'''), minimum version 6, 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. Currently, the Oracle JDK version 8 is recommended for building Robocode.
  
* Eclipse ([https://eclipse-tutorial.dev.java.net/ Eclipse tutorial])
+
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.
* 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.
+
==== Setting up Java Environment Variables ====
  
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.
+
You must set up the environment variable named '''JAVA_HOME''' and extend another environment variable named '''PATH'''. You find information on how to setup JAVA_HOME and PATH on the net, e.g. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html here].
  
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.
+
'''JAVA_HOME must be set up point to the root directory of the JDK you intend to use.'''
  
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.
+
The PATH environment variable must be extended in order to locate the Java commands like 'java', 'javac' and lots of other tools in the JDK. Extending PATH is considered best practice when setting up the Java development environment, and makes it possible for other tools like e.g. Maven to locate the proper JDK tools. It also makes it possible for you to detirmine which JRE that is being used when running a Java application by writting <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.8.0_162"</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.8.0_162/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 on how to set up your JAVA_HOME and PATH environment variables for your specific OS, please read the installation notes provided for the Oracle JDK 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 instructions from Oracle:'''
 +
* [https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html JDK 8 and JRE 8 Installation Start Here].
 +
* [https://www.oracle.com/technetwork/java/javase/certconfig-2095354.html Oracle JDK 8 and JRE 8 Certified System Configurations Contents] 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 ====
+
* Git and GitHub ([http://www.vogella.com/articles/Git/article.html Tutorial])
 +
* Maven ([http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Tutorial])
 +
* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
  
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 Git/GitHub, Maven, or Eclipse. 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 [http://java.sun.com/j2se/1.5.0/install.html here].
+
Eclipse is not required for building Robocode, meaning that you are free to use any IDE of your choice. However, all set up for building Robocode has primarily been focused on Eclipse, and the same goes for this guide. If you manage to setup Robocode for e.g. IntelliJ IDEA or any other IDE, you are welcome to write a guide for how to set up Robocode for your particular IDE as other developers might be very interested in using the same IDE.
  
==== Install Eclipse ====
+
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 fork], if you want to.
  
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.
+
In order to get build Robocode, Maven must be installed on your system. At present day, Maven 3.5.4 is the newest version and is able to build Robocode. Read more about how to install Maven [https://maven.apache.org/install.html here]. Note that the [https://github.com/takari/maven-wrapper Maven Wrapper] is being used by Robocode. Hence, you must run this Maven command from a command prompt or shell inside the your root directory for Robocode:
  
==== Create a workspace for Robocode ====
+
  mvn -N io.takari:maven:wrapper -Dmaven=3.5.4
  
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.
+
This will create the Maven Wrapper files for you guaranteed to run as Maven version 3.5.4, even if you might have a newer Maven installed on your system. You'll get a directory named ".mvn" and these two script files "mvnw" and "mvnw.cmd". You build Robocode by using the mvnassembly.sh or mvnassembly.cmd files, which makes use of the Maven Wrapper.
  
==== Use Subversive or Subclipse ====
+
You don't have to worry too much about how to set up Eclipse for Robocode as the provided sources contain all configuration files needed for Eclipse. Some of these files are generated using Maven's built-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 origin/head of the Robocode sources.
  
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.
+
=== Getting sources from GitHub ===
  
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.
+
In the following, I assume that you want to '''Git clone''' the sources from GitHub using a [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 download the sources as a plain .zip file from either [https://github.com/robo-code/robocode/archive/master.zip GitHub] or [https://sourceforge.net/projects/robocode/files/robocode%20sources/ SourceForge]. However, if you want to regularly update your local source files with the newest sources from the Git repository and the ability to commit and/or merge or fork changes, you will need to use a Git client.
  
==== How to install Subversive ====
+
The URL of the sources at GitHub is:
 +
[https://github.com/robo-code/robocode.git https://github.com/robo-code/robocode.git]
  
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:
+
==== How to build distribution files? ====
  
* Subversive SVN Team Provider Plugin 0.7.3 or newer.
+
In order to build the distribution files containing the installer setup file (robocode-x.x.x-setup.jar) and a .zip file containing all the sources (robocode-x.x.x-src.zip) you must call the '''mvnassembly''' script from the command-line when standing within the root directory of the Robocode sources.
* 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:
+
On Windows:
 +
  mvnassembly
  
# In Eclipse you must select 'Help' -> 'Software Updates...'' from the menu.
+
On *nix:
# Then you select the 'Available Software' tab
+
  ./mvnassembly.sh
# 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 ===
+
This will build the distribution files, which will be put into the sub-directory named ''robocode.distribution/target''.
  
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).
+
'''mvnassembly''' is a script that compiles all sources of the Robocode game, creates javadoc html files, run test units, and finally creates the target distribution files. The first time this script is run, it will need to download a huge amount of .jar files from various Maven repositories and which contains Maven plugins etc. used for building Robocode. So please be patient with it the first time.
  
==== Checkout sources from the SVN ====
+
==== Robocode plugins ====
  
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.
+
Two plugins exist for Robocode:
 +
* Testing plugin, which contains the testbed for testing bots.
 +
* .NET plugin, which makes it possible to run bots compiled for .NET, and packaged as .dll files.
  
If you want to checkout the sources for the trunk/head, you must use this URL:
+
Hence, a new Robot feature in Robocode should take the .NET plugin into account, as the .NET-based robots must behave the same way as the Java-based robots.
  https://robocode.svn.sourceforge.net/svnroot/robocode/robocode/trunk
+
Building the .NET plugin is a requires a big setup, and is described in a ReadMe.txt file within the source code for the .NET plugin (/plugins/dotnet).
  
If you instead want to checkout the sources for a specific Robocode version, you must use this URL:
+
=== Setting up Eclipse for developing on Robocode ===
  https://robocode.svn.sourceforge.net/svnroot/robocode/robocode/tags/VER_X_X_X
 
..where X_X_X must be replaced with a real version number, e.g. '1_5_3' for version 1.5.3
 
  
When you have entered or copy-and-pasted the URL into the checkout window you press OK. Now all the sources of the selected branch will be checked out from the SVN.
+
Here follows a description of how to setup Eclipse for developing on Robocode.
  
==== Preparing command-line tools ====
+
==== Software Requirements for Eclipse IDE ====
  
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.
+
Here follows the recommended software needed to start developing on Robocode with the Eclipse IDE:
  
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.
+
'''Required:'''
 +
* Oracle JDK 6 ([http://www.oracle.com/technetwork/java/javase/downloads/index.html download]) must be pre-installed.
 +
* Eclipse IDE for Java Developers([http://www.eclipse.org/downloads/ download]). The Juno, Kepler, Luna works fine for Robocode and supports Git.
  
On Windows:
+
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.
  cd tools
 
  loadTools
 
  
On Linux:
+
==== Create a workspace for Robocode ====
  cd ./tools
 
  ./loadTools.sh
 
  
==== Preparing your workspace for Eclipse ====
+
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.
  
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:
+
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.
  
* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide to using Eclipse with Maven 2.x]
+
==== M2_REPO class path variable ====
  
I highly recommend you to read this in order to understand how Eclipse and Maven works together.
+
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.
  
First, we need to create all the required Eclipse files, which we do with another Maven command.
+
When calling the 'mvnassembly' script or alternatively start off Maven within the root of the robocode sources by calling e.g. 'mvn clean install', Maven will download all required libraries from other sites into your local Maven repository. Note that you will need to locate your local Maven repository. Under Windows your Maven repository is put into your %USERPROFILE% directory, and on Linux is put into your home directory (~). The Maven repository will be put under .m2/repository.
  
On Windows:
+
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>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (Linux).
  mvn eclipse:eclipse
 
  
On Linux:
+
When Eclipse asks you if it should rebuild the workspace, you select 'Yes'.
  ./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.
+
==== Configure JDK for your workspace ====
  
On Windows:
+
You must setup which JDK that will be used for compiling (and running) Robocode in your workspace.
  mvn compile
+
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 6 and press 'Finish' or Enter. Make sure to select a JDK and ''not'' a JRE, as a JRE is not sufficient as it lacks the tools available with the JDK.
 +
# 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:
+
==== Importing sources of Robocode using Git ====
  ./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'.
+
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 Git (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 169: Line 184:
 
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
 
 
This will build the distribution files, which will be put into the sub-directory named ''target''.
 
  
 
=== Robocode developers and contributions ===
 
=== Robocode developers and contributions ===
Line 188: Line 191:
 
== See also ==
 
== 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.
 
* [[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://robocode.svn.sourceforge.net/viewvc/robocode Browse the sources] of Robocode.
+
* [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://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].
 
* [http://groups.google.com/group/robocode-developers Robocode developers discussion group].
Line 201: Line 204:
 
* [http://subclipse.tigris.org/ Subclipse] is also 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://tortoisesvn.net TortoiseSVN], a Subversion client for Windows.
* [http://www.open.collab.net/downloads/subversion/ CollabNets Bubversion], a Subversion client for both Windows and Linux.
+
* [http://www.open.collab.net/downloads/subversion/ CollabNets Subversion], a Subversion client for both Windows and Linux.
  
 
[[Category:Robocode Documentation]]
 
[[Category:Robocode Documentation]]
 
[[Category:Eclipse IDE]]
 
[[Category:Eclipse IDE]]

Revision as of 00:51, 20 October 2018

This guide describes how to build the Robocode application, i.e. the game itself, and not how to build bots for Robocode.

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

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

Requirements

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

  • Oracle JDK 8 (Java SE Development Kit 8 Downloads). Note that only version 6, 7, and 8 will work. Newer versions are not supported (yet) and are almost guaranteed to cause building problems.
  • Source files for Robocode (on GitHub), which you get by doing a Git clone.
  • 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 and requires a big effort to grasp and understand. There is practically no documentation available that describe the internal logic, architecture, game rules, coding conventions etc. So you will probably be on your own when trying to figure out how Robocode it put together.

An Internet connection is required for building Robocode distribution files as the build tool (Maven) needs access to remote repositories, which contains various libraries and binaries. Some libraries are used for building Robocode, and others are used for running Robocode, and hence need to be put into the distribution files. In order to get updates to the sources of Robocode when new versions emerge, an Internet connection is also critical to download changed sources and merge the changes with your version of the sources etc.

Note that all sources of Robocode are for Java 6, meaning that Robocode is able to run on very old Java versions, which is intentional.

Installing the JDK

Robocode is being developed using Oracle's Java SE, and requires the Java Developer Kit (JDK), minimum version 6, 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. Currently, the Oracle JDK version 8 is recommended 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.

Setting up Java Environment Variables

You must set up the environment variable named JAVA_HOME and extend another environment variable named PATH. You find information on how to setup JAVA_HOME and PATH on the net, e.g. here.

JAVA_HOME must be set up point to the root directory of the JDK you intend to use.

The PATH environment variable must be extended in order to locate the Java commands like 'java', 'javac' and lots of other tools in the JDK. Extending PATH is considered best practice when setting up the Java development environment, and makes it possible for other tools like e.g. Maven to locate the proper JDK tools. It also makes it possible for you to detirmine which JRE that is being used when running a Java application by writting java -version in the command-line/shell, and detirmine which Java compiler that is being used by writting javac -version instead.

Windows:

  • JAVA_HOME is set to e.g. JAVA_HOME="C:\Program Files\Java\jdk1.8.0_162".
  • 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.8.0_162/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 on how to set up your JAVA_HOME and PATH environment variables for your specific OS, please read the installation notes provided for the Oracle JDK here:

Installation instructions from Oracle:

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 Git/GitHub, Maven, or Eclipse. 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. :-)

Eclipse is not required for building Robocode, meaning that you are free to use any IDE of your choice. However, all set up for building Robocode has primarily been focused on Eclipse, and the same goes for this guide. If you manage to setup Robocode for e.g. IntelliJ IDEA or any other IDE, you are welcome to write a guide for how to set up Robocode for your particular IDE as other developers might be very interested in using the same IDE.

All sources of Robocode are available at GitHub. At GitHub, you can download sources as a zipped file or create your own fork, if you want to.

In order to get build Robocode, Maven must be installed on your system. At present day, Maven 3.5.4 is the newest version and is able to build Robocode. Read more about how to install Maven here. Note that the Maven Wrapper is being used by Robocode. Hence, you must run this Maven command from a command prompt or shell inside the your root directory for Robocode:

 mvn -N io.takari:maven:wrapper -Dmaven=3.5.4

This will create the Maven Wrapper files for you guaranteed to run as Maven version 3.5.4, even if you might have a newer Maven installed on your system. You'll get a directory named ".mvn" and these two script files "mvnw" and "mvnw.cmd". You build Robocode by using the mvnassembly.sh or mvnassembly.cmd files, which makes use of the Maven Wrapper.

You don't have to worry too much about how to set up Eclipse for Robocode as the provided sources contain all configuration files needed for Eclipse. Some of these files are generated using Maven's built-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 origin/head of the Robocode sources.

Getting sources from GitHub

In the following, I assume that you want to Git clone the sources from GitHub using a 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 download the sources as a plain .zip file from either GitHub or SourceForge. However, if you want to regularly update your local source files with the newest sources from the Git repository and the ability to commit and/or merge or fork changes, you will need to use a Git client.

The URL of the sources at GitHub is: https://github.com/robo-code/robocode.git

How to build distribution files?

In order to build the distribution files containing the installer setup file (robocode-x.x.x-setup.jar) and a .zip file containing all the sources (robocode-x.x.x-src.zip) you must call the mvnassembly script from the command-line when standing within the root directory of the Robocode sources.

On Windows:

 mvnassembly

On *nix:

 ./mvnassembly.sh

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

mvnassembly is a script that compiles all sources of the Robocode game, creates javadoc html files, run test units, and finally creates the target distribution files. The first time this script is run, it will need to download a huge amount of .jar files from various Maven repositories and which contains Maven plugins etc. used for building Robocode. So please be patient with it the first time.

Robocode plugins

Two plugins exist for Robocode:

  • Testing plugin, which contains the testbed for testing bots.
  • .NET plugin, which makes it possible to run bots compiled for .NET, and packaged as .dll files.

Hence, a new Robot feature in Robocode should take the .NET plugin into account, as the .NET-based robots must behave the same way as the Java-based robots. Building the .NET plugin is a requires a big setup, and is described in a ReadMe.txt file within the source code for the .NET plugin (/plugins/dotnet).

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:

  • Oracle JDK 6 (download) must be pre-installed.
  • Eclipse IDE for Java Developers(download). The Juno, Kepler, Luna works fine for Robocode and supports Git.

Please consult the installation notes provided for Eclipse in order to find out how to install Eclipse for your specific OS.

Create a workspace for Robocode

When you have setup and installed Eclipse on your system (if you did not have it on your system already), a workspace must be created for Robocode.

The first time you start up a newly installed Eclipse, it will ask for a directory for your workspace. I suggest that you create a workspace named robocode-workspace or similar and create the workspace on a partition or directory like e.g. C: (on Windows) or ~ (on Linux) - or any other directory of your choice. If you have already got a workspace, e.g. the default one suggested by Eclipse, you can create a new workspace if you wish by selecting 'File' -> 'Switch Workspace' -> 'Other...' from the menu.

M2_REPO class path variable

One of the first things you need to do in Eclipse is to set up the M2_REPO class path variable for Eclipse, which points to your local Maven 2 repository. That is, Eclipse uses the M2_REPO class path variable for locating the Maven repository containing various libraries used for compiling Robocode etc. But before you can setup the M2_REPO class path in Eclipse, you must run the 'mvnassembly' command described earlier if you have not already done that.

When calling the 'mvnassembly' script or alternatively start off Maven within the root of the robocode sources by calling e.g. 'mvn clean install', Maven will download all required libraries from other sites into your local Maven repository. Note that you will need to locate your local Maven repository. Under Windows your Maven repository is put into your %USERPROFILE% directory, and on Linux is put into your home directory (~). The Maven repository will be put under .m2/repository.

To setup the M2_REPO class path in Eclipse, you must go to the menu bar and select 'Window' -> 'Preferences'. On the Preferences window expand the 'Java' -> 'Build Path' and select the 'Classpath Variables'. On the page for the Classpath Variables, you click on the 'New...' button, and enter M2_REPO as name. Next, you click on the 'Folder...' button and navigate to where you have your .m2/repository directory located (in %USERPROFILE% under Windows, and ~ under Linux), e.g. C:/Users/Flemming/.m2/repository (Windows) or /home/fnl/.m2/repository (Linux).

When Eclipse asks you if it should rebuild the workspace, you select 'Yes'.

Configure JDK for your workspace

You must setup which 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 6 and press 'Finish' or Enter. Make sure to select a JDK and not a JRE, as a JRE is not sufficient as it lacks the tools available with the JDK.
  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.

Importing sources of Robocode using Git

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 Git (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