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

From Robowiki
Jump to navigation Jump to search
m (Added screenshots)
 
(40 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.
  
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 IntelliJ IDEA setup ==
 
 
== Developer's Guide for building Robocode using Eclipse ==
 
  
 
=== 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 application, and describes all the basic stuff required to compile and run Robocode within [https://www.jetbrains.com/idea/ IntelliJ IDEA].
 
 
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].
 
 
 
=== Introduction ===
 
 
 
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.
 
 
 
Basically, all you need is the sources of Robocode, which can be downloaded as a .zip file or downloaded from the Subversion repository, and [http://maven.apache.org/ Maven] installed. Maven is being used in order to build everything in the Robocode project. However, if you want to work with the sources of Robocode, you might of course want to use an IDE for compiling and run Robocode on the fly to see the effect of your work.
 
 
 
Batch files and shell scripts are provided for building Robocode under Windows and Linux (including Mac OS X). These scripts have been developed for Windows XP/Vista and Ubuntu 8.10 (Linux). Please notice that the Linux setup should also work for e.g. Solaris, FreeBSD etc.
 
 
 
=== What skills do you need? ===
 
 
 
* Eclipse ([https://eclipse-tutorial.dev.java.net/ Eclipse tutorial])
 
* Subversion ([http://svnbook.red-bean.com/ Subversion book])
 
* Maven ([http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html Maven in 5 Minutes])
 
 
 
This guide is focusing on how to build and run Robocode using the [http://www.eclipse.org/ Eclipse], which is supported by Robocode. Eclipse is a very popular IDE that comes free of charge, and which supports SVN access to the sources, a rich source code editor, automatic compilation, has a big supporting community, lot's of plugins, and much much more.
 
 
 
This guide assumes that you have some basic knowledge about how to download, install and use Eclipse. Hence, this guide will not teach you how to use Eclipse, but rather focus on how to build Robocode within Eclipse. The same applies to other tools used within this guide.
 
 
 
Please notice that you do not have to be an expert in Eclipse, Subversion, and Maven. But you need some basic knowledge about these in order to understand how to build Robocode. In fact, trying to build Robocode might actually be a very good way of learning these tools, if you don't know them already or miss some practical experience with these.
 
 
 
You don't have to worry too much about how to setup Eclipse for Robocode as the provided sources in SVN contains all configuration files needed by Eclipse. Some of these files are generated using Maven's build-in support for Eclipse. However, you still need to do some basic pre-configuration of Eclipse before you'll be able to get started with working on Robocode. You should only need to set up a workspace for Robocode once. However, you will need to update the sources from SVN once in a while and merge these with your local changes in order to keep up-to-date with the current versions of Robocode - at least if you work on the trunk/head branch of the Robocode sources.
 
 
 
=== Software Requirements ===
 
 
 
'''Required:'''
 
* Sun JDK 5.0 ([http://java.sun.com/javase/downloads/index_jdk5.jsp download]).
 
* Eclipse Classic 3.4.1 or newer ([http://www.eclipse.org/downloads/ download]).
 
* A Subversion client like TortoiseSVN 1.5.7 or newer ([http://tortoisesvn.net/downloads download]) (for Windows) ... or CollabNet Subversion Command-Line Client v1.5.5 ([http://www.collab.net/downloads/subversion/ download]) for Windows and Linux.
 
 
 
'''Highly Recommended:'''
 
* [http://www.eclipse.org/subversive/ Eclipse Subversive] 0.7.3 or newer (installation procedure described later) or [http://subclipse.tigris.org/ Subclipse] 1.4.7 or newer (installation procedure is not described in this guide).
 
  
==== Install Sun JDK 5.0 ====
+
If you just need to study the sources, you can do it from [https://github.com/robo-code/robocode GibHub], where it is possible to download the source code as a zip file under 'Code'.
  
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.
+
=== Requirements ===
  
It is important that the Java vendor is '''Sun''' in order to guarantee that you'll not run into some unexpected problems when using the Java compiler etc. Most problems caused by building Robocode (and when compiling robots for Robocode) is caused by Java versions from other vendors than Sun.
+
To get started with building Robocode you need:
 +
* An Internet connection, as Robocode has dependencies to libraries that are available on public binary repositories.
 +
* [https://git-scm.com/downloads Git]
 +
* [https://www.jetbrains.com/idea/download/ IntelliJ IDEA]
 +
* JDK 8, e.g. [https://adoptopenjdk.net/?variant=openjdk8 AdoptOpenJDK 8]
  
Also make sure that you use '''version 5.0''' of the JDK, not a never version like e.g. the JDK 6. Otherwise you might experience problems when building Robocode, and if you distribute your version of Robocode, your version will require Java 6 in order to run properly. Currently, Robocode must be able to run under Java 5.0.
+
Note that JDK 8 is required for Robocode to ensure all binaries can run on Java 8. If you build a customized version of your own, you are of course free to use a newer JDK version. But notice that the build tools might not be work with newer Java versions. So you'll need to fix this by yourself.
  
When installing the JDK, I recommend that you install the sources for Java as these are very useful when debugging you sources when working on Robocode. However, it is not a requirement to install the Java sources provided with the JDK.
+
Make sure that your JAVA_HOME and PATH is set up to use the JDK 8 when building the Robocode application. There is a good guide [https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux here].
  
==== Set the Environment Settings for Java ====
+
=== Cloning the Robocode project ===
  
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), and <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 (used for building Robocode) is depending on the JAVA_HOME environment variable, and must know where to locate the Sun JDK 1.5.
+
You need to download the source files for the Robocode project into your PC using Git with this command line:
  
If you want more information of how to setup your JAVA_HOME and PATH environment variables for your specific OS, please read the installation notes provided for the Sun JDK 5.0 [http://java.sun.com/j2se/1.5.0/install.html here].
+
    git clone https://github.com/robo-code/robocode.git robocode-proj
  
==== Install Eclipse ====
+
This downloads the Robocode source files into a directory named 'robocode-proj' into the current directory.
  
When the Sun JDK 5.0 is avaiable on your system, you must install the Eclipse 3.4 if it is not available on your system already. Please notice, that older versions of Eclipse (like e.g. Eclipse 3.2 provided with Ubuntu 8.10) will not work with the setup used in this guideline. Consult the installation notes provided for Eclipse in order to find out how to install Eclipse 3.4 on your specific OS.
+
=== Building the Robocode application ===
  
==== Create a workspace for Robocode ====
+
Robocode is built by running using Gradle standing in the 'robocode-proj' directory:
  
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 created a workspace, e.g. the one that Eclipse propose as default, the first time Eclipse is started it, you can create a new workspace if you wish by selecting File -> Switch Workspace -> Other... from the menu.
+
    ./gradlew build
  
==== Use Subversive or Subclipse ====
+
This step is required to easy importing the project into IntelliJ IDEA, but also the quickest way to build and test 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.
+
=== Setup Robocode for IntelliJ ===
  
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.
+
First, open the 'robocode-project' directory in IntelliJ.
  
==== How to install Subversive ====
+
Secondly, set the JDK for the Robocode project, which needs to be JDK 8.
  
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:
+
From the menu, select:
 +
File > Project Structure | Platform Settings | SDKs > + (plus sign) > Add JDK
  
* Subversive SVN Team Provider Plugin 0.7.3 or newer.
+
Select the home directory of your JDK 1.8 installation.
* 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:
+
The last step is to align IDEA with the Gradle setup. You do this by running the 'Reload All Gradle Projects', which is available by pressing the "refresh button" with the Gradle tool window in its top-left corner.
  
# In Eclipse you must select 'Help' -> 'Software Updates...'' from the menu.
+
[[File:Gradle refresh.png]]
# 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 ===
+
=== Run the Robocode application ===
  
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).
+
You can run or debug Robocode as soon as Robocode has been set up in IntelliJ. You can launch it from the toolbar with "Robocode app" and press the "play" button for running Robocode or the "bug" button for running Robocode in debugging mode.
  
==== Checkout sources from the SVN ====
+
[[File:Run Robocode app.png|Run Robocode app from IntelliJ]]
  
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.
+
=== Build the Installer for Robocode ===
  
If you want to checkout the sources for the trunk/head, you must use this URL:
+
You build the Robocode installer (setup file) using Gradle from the command line:
  https://robocode.svn.sourceforge.net/svnroot/robocode/robocode/trunk
 
  
If you instead want to checkout the sources for a specific Robocode version, you must use this URL:
+
  ./gradlew build
  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.
+
Gradle puts the installer into /build/robocode-x.x.x.x-setup.jar
  
==== Preparing command-line tools ====
+
=== Setting the version of the Robocode application ===
  
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.
+
The version of Robocode can be changed in this file:
 +
\buildSrc\src\main\kotlin\net.sf.robocode.java-conventions.gradle.kts
  
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.
+
Look for a line like this:
  
On Windows:
+
    version = "1.9.4.2"
  cd tools
 
  loadTools
 
 
 
On Linux:
 
  cd ./tools
 
  ./loadTools.sh
 
 
 
==== Preparing your workspace for Eclipse ====
 
 
 
Next we must prepare your workspace for Eclipse. Eclipse needs the project files, class files, and other configuration files in order order to let you view, edit, and compile Robocode. Maven provides support for using Eclipse with Maven. You can read more about this here:
 
 
 
* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide to using Eclipse with Maven 2.x]
 
 
 
I highly recommend you to read this in order to understand how Eclipse and Maven works together.
 
 
 
First, we need to create all the required Eclipse files, which we do with another Maven command.
 
 
 
On Windows:
 
  mvn eclipse:eclipse
 
 
 
On Linux:
 
  ./mvn.sh eclipse:eclipse
 
 
 
Next, you should compile the sources of Robocode in order to have your local Maven repository created and prepared for later.
 
 
 
On Windows:
 
  mvn compile
 
 
 
On Linux:
 
  ./mvn.sh compile
 
 
 
Now your Robocode workspace is ready almost ready. You just need to import all the projects into your Eclipse workspace. You do this by starting up Eclipse with your Robocode workspace. From the menu bar you select 'File' -> 'Import...' -> 'Existing Projects into Workspace'. Now select the root directory to be the root path of your Robocode workspace. You should see a list of Robocode project. When you do, you must press 'Finish'.
 
 
 
The last thing you need to do is to set up the M2_REPO class path variable for Eclipse, so Eclipse knows where to locate the Maven repository. When building Robocode using Maven, Maven will download all required classes from other sites into this local Maven repository. Hence, Eclipse needs to know the class path for this Maven repository in order to compile all the sources of Robocode. So you need to locate your local Maven repository. Under Windows your Maven repository is put into your %USERPROFILE% directory, and on Linux is put into your home directory (~).
 
 
 
In Eclipse, you go to the menu bar and select 'Window' -> 'Preferences'. On the Preferences window expand the 'Java' -> 'Build Path' and select the 'Classpath Variables'. On the page for the Classpath Variables, you click on the 'New...' button, and enter ''M2_REPO'' as name. Next, you click on the 'Folder...' button and navigate to where you have your .m2/repository directory located (in %USERPROFILE% under Windows, and ~ under Linux), e.g. <code>H:/Users/Flemming/.m2/repository</code> or <code>/home/fnl/.m2/repository</code>.
 
 
 
When Eclipse ask you if you want to rebuild the workspace, you select 'Yes' in order to rebuild everything so you are ready to work on Robocode.
 
 
 
==== How to start Robocode in Eclipse? ====
 
 
 
When all sources builds without errors (warnings are expected), you are able to launch Robocode. You do this by selecting 'Run' -> 'Run Configurations...' from th Menu. On the window that shows up, you expand the 'Java Applications', select 'Robocode', and press the 'Run' button.
 
 
 
==== How to run the unit tests? ====
 
 
 
When you want to run the unit test from within Eclipse, you must do this from the the Package Explorer, where you right-click on the 'robocode.tests' project and select 'Run As' -> 'JUnit Test'. Now all available unit tests will run automatically.
 
 
 
Alternatively you can start the tests from the command-line by standing on your robocode workspace, and write the following Maven command.
 
 
 
On Windows:
 
  mvn test
 
 
 
On Linux:
 
  ./mvn.sh test
 
 
 
==== How to build the distribution files? ====
 
 
 
In order to build the distribution files containing the installer setup file (robocode-x.x.x-setup.jar) and a .zip file containing all the sources (robocode-x.x.x-src.zip) you start the following batch/shell file wrong the command-line within the robocode workspace directoty.
 
 
 
On Windows:
 
  mvnassembly
 
 
 
On Linux:
 
  ./mvnassembly
 
 
 
This will build the distribution files, which will be put into the sub-directory named ''target''.
 
  
 
=== Robocode developers and contributions ===
 
=== 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.
+
Robocode application developers have a discussion group [http://groups.google.com/group/robocode-developers here]. Anybody interested in a discussion or advice about contributing with a feature or modification for Robocode is welcome to this group.
 
 
== See also ==
 
* [[Robocode/Old Developers Guide for building Robocode|Old version]] of the Developer's Guide for building Robocode for Robocode versions prior to version 1.7.
 
* [http://robocode.svn.sourceforge.net/viewvc/robocode Browse the sources] of Robocode.
 
* [http://sourceforge.net/project/showfiles.php?group_id=37202&package_id=218677 Download the sources] of Robocode.
 
* [http://groups.google.com/group/robocode-developers Robocode developers discussion group].
 
  
== References ==
 
* The [http://sourceforge.net/projects/robocode Robocode project] on SourceForge.
 
* [http://sourceforge.net/svn/?group_id=37202 How to access] the SVN Repository for Robocode.
 
* [http://www.eclipse.org/ Eclipse] - an open development platform supported by Robocode.
 
* [http://maven.apache.org/ Apache Maven] used for building Robocode.
 
* [http://maven.apache.org/guides/mini/guide-ide-eclipse.html Guide] to using Eclipse with Maven 2.x.
 
* [http://www.eclipse.org/subversive/ Eclipse Subversive] is a plugin used for accessing Subversion from Eclipse.
 
* [http://subclipse.tigris.org/ Subclipse] is also a plugin used for accessing Subversion from Eclipse.
 
* [http://tortoisesvn.net TortoiseSVN], a Subversion client for Windows.
 
* [http://www.open.collab.net/downloads/subversion/ CollabNets Bubversion], a Subversion client for both Windows and Linux.
 
  
 
[[Category:Robocode Documentation]]
 
[[Category:Robocode Documentation]]
 
[[Category:Eclipse IDE]]
 
[[Category:Eclipse IDE]]

Latest revision as of 22:15, 24 June 2021

This guide describes how to build the Robocode application, i.e. the game itself.

Developer's Guide for building Robocode with IntelliJ IDEA setup

Notice

This guide is intended for experienced Java developers, who want to work on the Robocode application, and describes all the basic stuff required to compile and run Robocode within IntelliJ IDEA.

If you just need to study the sources, you can do it from GibHub, where it is possible to download the source code as a zip file under 'Code'.

Requirements

To get started with building Robocode you need:

  • An Internet connection, as Robocode has dependencies to libraries that are available on public binary repositories.
  • Git
  • IntelliJ IDEA
  • JDK 8, e.g. AdoptOpenJDK 8

Note that JDK 8 is required for Robocode to ensure all binaries can run on Java 8. If you build a customized version of your own, you are of course free to use a newer JDK version. But notice that the build tools might not be work with newer Java versions. So you'll need to fix this by yourself.

Make sure that your JAVA_HOME and PATH is set up to use the JDK 8 when building the Robocode application. There is a good guide here.

Cloning the Robocode project

You need to download the source files for the Robocode project into your PC using Git with this command line:

   git clone https://github.com/robo-code/robocode.git robocode-proj

This downloads the Robocode source files into a directory named 'robocode-proj' into the current directory.

Building the Robocode application

Robocode is built by running using Gradle standing in the 'robocode-proj' directory:

   ./gradlew build

This step is required to easy importing the project into IntelliJ IDEA, but also the quickest way to build and test Robocode.

Setup Robocode for IntelliJ

First, open the 'robocode-project' directory in IntelliJ.

Secondly, set the JDK for the Robocode project, which needs to be JDK 8.

From the menu, select: File > Project Structure | Platform Settings | SDKs > + (plus sign) > Add JDK

Select the home directory of your JDK 1.8 installation.

The last step is to align IDEA with the Gradle setup. You do this by running the 'Reload All Gradle Projects', which is available by pressing the "refresh button" with the Gradle tool window in its top-left corner.

Gradle refresh.png

Run the Robocode application

You can run or debug Robocode as soon as Robocode has been set up in IntelliJ. You can launch it from the toolbar with "Robocode app" and press the "play" button for running Robocode or the "bug" button for running Robocode in debugging mode.

Run Robocode app from IntelliJ

Build the Installer for Robocode

You build the Robocode installer (setup file) using Gradle from the command line:

  ./gradlew build

Gradle puts the installer into /build/robocode-x.x.x.x-setup.jar

Setting the version of the Robocode application

The version of Robocode can be changed in this file: \buildSrc\src\main\kotlin\net.sf.robocode.java-conventions.gradle.kts

Look for a line like this:

   version = "1.9.4.2"

Robocode developers and contributions

Robocode application developers have a discussion group here. Anybody interested in a discussion or advice about contributing with a feature or modification for Robocode is welcome to this group.