Robowiki - User contributions [en]

Robocode/Developers Guide for building Robocode

2021-06-24T21:15:11Z

FlemmingLarsen: Added screenshots

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 [https://www.jetbrains.com/idea/ IntelliJ IDEA].

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

=== 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.
* [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]

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 [https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux 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.

[[File: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.

[[File:Run Robocode app.png|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 [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.

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

File:Gradle refresh.png

2021-06-24T21:14:44Z

FlemmingLarsen:

Refreshing project from Gradle panel in IntelliJ

Robocode/Developers Guide for building Robocode

2021-06-24T21:12:14Z

FlemmingLarsen:

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 [https://www.jetbrains.com/idea/ IntelliJ IDEA].

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

=== 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.
* [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]

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 [https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux 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.

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

[[File:Run Robocode app.png|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 [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.

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

Robocode/Developers Guide for building Robocode

2021-06-24T21:11:08Z

FlemmingLarsen:

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 [https://www.jetbrains.com/idea/ IntelliJ IDEA].

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

=== 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.
* [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]

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 [https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux 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.

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

[[File:Run Robocode app.png|thumb|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 [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.

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

File:Run Robocode app.png

2021-06-24T21:10:35Z

FlemmingLarsen:

Run Robocode app from IntelliJ

Robocode/Developers Guide for building Robocode

2021-04-09T23:37:38Z

FlemmingLarsen: Brand new developer guide for building Robocode with Gradle and for IntelliJ IDEA

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 [https://www.jetbrains.com/idea/ IntelliJ IDEA].

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

=== 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.
* [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]

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 [https://www.baeldung.com/java-home-on-windows-7-8-10-mac-os-x-linux 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.

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

=== 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.1"

=== Robocode developers and contributions ===

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.

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

Robocode/FAQ

2020-10-25T09:40:32Z

FlemmingLarsen:

Frequently asked questions about Robocode.

== [[Robocode/Download|Installing]] and [[Robocode/Getting Started|using]] ==
; '''I can't install Robocode.'''
: Please see [[Robocode_Download_And_Install|these instructions]].

; '''I get this error when trying to start Robocode: "'JAVA' is not recognized as an internal or external command, operable or batch file".'''
: This is caused by an unknown path to your Java installation. Please follow [[Robocode/System_Requirements#PATH_must_be_set|these instructions]].

; '''Can I play Robocode online?'''
: Robocode is not an "online" game, so you can't, for example, share a battle with your friends in real time over the Internet. But you can upload your bots to places such as GitHub or Dropbox, and join any of the existing competitions such as [https://literumble.appspot.com/ RoboRumble] (enter [[RoboRumble/Enter The Competition|here]]), or organize one with your friends.

;'''What is the difference between a set method like setAhead() and ahead() without the set-prefix?'''
: The difference between a method like <code>ahead()</code>, and the method <code>setAhead()</code> is that set-methods are only available with the AdvancedRobot. The difference is that you can call multiple setters like e.g. <code>setAhead()</code>, <code>setTurnGunLeft()</code>, and <code>setFire()</code> in the same turn. These set commands will first take effect, i.e. execute, when you call the <code>execute()</code> method explicitly in a turn. Methods that are not setters like e.g. <code>ahead()</code>, <code>turnGunLeft()</code>, and <code>fire()</code> will execute independently and take one to many turns to complete, as one command will need to execute and complete before the next command is being executed. Setters are called in the same turn when <code>execute()</code> is called. So the method <code>ahead()</code> is actually the same as <code>setAhead()</code> + <code>execute()</code>, and in that order. The set methods can be seen as "fire and forget" methods that are executed immediately, whereas the methods like <code>ahead()</code> must first complete its movement, turning, firing etc. before the next command is being run. Hence those commands need to wait for the other commands to complete first before the method itself will be executed.

; '''How do I get started?'''
: See [[Robocode/Getting Started|Getting Started]] and [[Robocode/My First Robot|My First Robot]].

; '''What can robots do?'''
: Many things. They can [[Movement|move]], turn, scan robots with their [[Radar]], aim their gun and [[Targeting|fire bullets]], and get information about the world around them. See the [http://robocode.sourceforge.net/docs/robocode/ Robocode API].

; '''Should I download robots from the Internet?'''
: Yes. More robots makes your Robocode experience more fun. See [[Robocode/Downloading Robots|Downloading Robots]].

; '''I have downloaded a robot from the Web, but I don't know how to use it, because it doesn't appear anywhere.'''
: By default, robots are read from the <code>/robocode/robots</code> directory. You can select "Robot -> Import Downloaded Robot" to copy a robot JAR to this directory from another location. Also, you can configure Robocode to read robots from additional locations using the Properties dialog.

; '''I have seen that many bots are packaged into ".jar" files. How do I package my bot?'''
: Select, "Robot -> Package robot for upload" from the menu, then enter your robot's details when prompted. See [[Robocode/Package Robot|Package Robot]].

; '''What do I have to do to see the source code of a robot?'''
: You can do two things. The first option is to open the Editor Window in Robocode and use the command in the File menu. The second option is to open the robot ".jar" file with a zip utility and find the source code there (assuming, of course, the robot is open source). See [[Robocode/Learning from Robots|Learning from Robots]].

;'''When I test my bots, Robocode is slow. Is there a way to execute the battles faster?'''
: When you are testing your robot, you want to execute many battles in a short time. Minimize the Robocode main screen to make it execute the battles at full speed.

;'''What is with the star "*" next to my robot's name?'''
: The asterisk to the right of a robot's name indicates that the robot is a development version, not a [[Robocode/Package Robot|packaged version]].

== [[Robocode/Game Physics|Game physics]] ==
; '''What are ticks, turns, and frames?'''
: A tick refers to one unit, which is also called a turn in Robocode. During one turn, you may perform one action as a Robot, or multiple (independent) actions as an AdvancedRobot. A frame is a unit of drawing to the Robocode client interface. If you are processing turns slowly, you will get one frame per tick / turn. However, if you up the turns per second beyond your computer's ability to render the frames, you will miss some frames of animation. This won't affect the robots' behavior, unless you foolishly added code in your <code>onPaint(Graphics2D)</code> method that alters your bots behavior. In that case, your bot will behave differently depending on whether or not the Paint button has been enabled, and if the framerate can keep up with the turnrate.

; '''Can I fire bullets with power higher than 3.0 or lower than 1.0?'''
:No and yes. You can't fire bullets with power greater than 3.0, but you can fire bullets with power as low as 0.1. If you call a firing function (i.e. <code>setFire()</code>) with a value greater than 3.0, Robocode will adjust it to 3.0, and if you call it with a power lower than 0.1 (except 0.0 which will not fire) it will adjust it to 0.1. Additionally, you can fire bullets with power less than 0.1 under one condition: when your robot has less than 0.1 energy left, in which case a bullet is fired with however much energy your robot had left.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#MAX_BULLET_POWER <code>Rules.MAX_BULLET_POWER</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#MIN_BULLET_POWER <code>Rules.MIN_BULLET_POWER</code>].

; '''How fast does a bullet travel?'''
: A bullet travels at a speed between 11.0 and 19.7 depending on the power. The more powerful the bullet, the slower. The formula to calculate it is <code>velocity = 20 - (3 * power)</code>.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getBulletSpeed(double) <code>Rules.getBulletSpeed()</code>].

; '''Does the robot velocity get added to the bullet velocity on firing?'''
: No, bullet velocity is not affected by robot velocity. It's kind of like the speed-of-light thing.

; '''Are bullets fired from the end of the barrel, or the center of the robot?'''
: They start at the center of the robot on the tick that you call <code>fire()/setFire()/setFireBullet()</code>.

; '''What is the range of a bullet?'''
: A bullet has no range. It keeps going until it hits a robot or a wall.

; '''What is the size of a bullet?'''
: A bullet has no size. Robocode treats them as line segments from one tick to the next.

; '''I want to fire a bullet every turn, but I can't. Why?'''
: Every time you fire, the gun generates some heat. You must wait till it is cool again to fire. If you give a fire order when your gun is hot, it will do nothing. The heat generated by a shot is <code>1 + (firepower / 5)</code>. The gun cools down at a default rate of 0.1 per turn (note that you can change this parameter when you run the battle, but nobody usually does). It means you can fire a 3.0 power bullet every 16 ticks.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getGunHeat(double) <code>Rules.getGunHeat()</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Robot.html#getGunCoolingRate() <code>Robot.getGunCoolingRate()</code>].

; '''How much damage does a bullet do? How do I gain or lose energy?'''
: You lose energy every time you hit a wall, you are hit by an enemy bullet, ram an enemy, or you fire your gun. The amount of energy you lose by being hit is <code>4 * bullet power + 2 * max(bullet power - 1 , 0)</code>. So the maximum amount is 16.0. When you fire, you spend a quantity of energy equal to the power of the bullet fired. When one of your bullets hits an enemy, you collect back <code>3 * bullet power</code> energy. When you hit an enemy bot, each bot takes 0.6 damage. If an [[AdvancedRobot]] (but not a [[Robot]] or [[JuniorRobot]]) hits a wall, it will take <code>max(abs(velocity) * 0.5 - 1, 0)</code> damage.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getBulletDamage(double) <code>Rules.getBulletDamage()</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getBulletHitBonus(double) <code>Rules.getBulletHitBonus()</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getWallHitDamage(double) <code>Rules.getWallHitDamage()</code>].

; '''Some times I get disabled. What happens?'''
: You can't kill yourself, so when your energy drops to zero because you hit a wall or you fire, your bot gets disabled. It will not be able to move nor fire. If you are lucky enough and one of your bullets in the air hits an enemy, you will get some energy back and recover from disabled status.

; '''I get disabled, but I my energy > 0. Why?'''
: There are a few possible causes. You may have called a getXXX() function - such as getVelocity() - too many times a turn. The limit is 10000 getXXX() function calls per turn. To avoid disabling in such situations, either store returned values in variables for future use or use a [[RobotStatus]] object obtained from [[StatusEvent]]. Another case in which you can get disabled is throwing an exception, which may disable your bot, even if you catch the exception. Also, if your bot gets stuck in an infinite (or very long) loop and skips many turns, it may also get disabled.

; '''How fast do I move?'''
: You can move at a maximum speed of 8.0 units/tick. You can modify (down) your maximum velocity by using <code>setMaxVelocity(...)</code>. Note that your bot will always accelerate to reach its maximum velocity.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#MAX_VELOCITY <code>Rules.MAX_VELOCITY</code>].

; '''How fast do I accelerate?'''
: You accelerate at 1 unit/tick, and you decelerate at 2 units/tick. For example, if you are moving at an speed of 8.0 and reverse your direction your velocities will be [6.0, 4.0, 2.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0].

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#ACCELERATION <code>Rules.ACCELERATION</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#DECELERATION <code>Rules.DECELERATION </code>].

; '''How fast do I turn?'''
: The faster you go, the slower you turn. The formula to calculate it in degrees is <code>10 - 0.75 * abs(velocity)</code>. The maximum turn rate is 10 degrees/turn.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#getTurnRate(double) <code>Rules.getTurnRate()</code>] and [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#MAX_TURN_RATE <code>Rules.MAX_TURN_RATE</code>].

; '''What is the size of a bot?'''
: The size of a bot is 36x36. Note, this is slightly smaller than the image of the bot. It is modeled as a non rotating square, so it's always the same regardless of its heading.

; '''It seems that Robocode doesn't follow standard physics. If my velocity is 0 and I accelerate (acceleration = 1) my final velocity is 1, but it should be 0.5. What happened?'''
: Time in Robocode, rather than being continuous, is in discrete "ticks". First acceleration is calculated, then velocity, and then position. So if you are stopped at a position 0 and you accelerate 1, your velocity next turn will be 1 and your position also 1.

; '''How can I detect when an enemy has fired?'''
: There is no direct way to detect when an enemy fired, but you can deduce it by monitoring the enemy [[energy drop]]. A drop between 0.1 and 3 usually means that it fired a bullet (there can be other reasons, such as a low energy bullet hit or a wall hit). Wall hits are (more or less) detectable as well. A deceleration > 2 means the bot hit a wall (or another bot). A deceleration <= 2 may be simple a bot hitting the brakes, or hitting a wall at velocity = 2, but since hitting a wall at that speed won't cause any damage, you can ignore that. AdvancedRobots take <code>abs(velocity) / 2 - 1 (Never < 0)</code> damage when hitting a wall, so by detecting (significant) wall-hits and adjusting the enemy drop accordingly, wall hits can be filtered out most of the time. This method fails when the enemy hits another robot.

; '''How can I detect the position and heading of an enemy bullet?'''
: You can't. There is no way to know it, directly or indirectly. But of course, you can always [[GuessFactor|guess]]...

; '''How fast can I turn my gun?'''
: The gun turns at 20 degrees per tick.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#GUN_TURN_RATE <code>Rules.GUN_TURN_RATE</code>].

; '''How fast can I turn my radar?'''
: It turns 45 degrees per tick.

: See [http://robocode.sourceforge.net/docs/robocode/robocode/Rules.html#RADAR_TURN_RATE <code>Rules.RADAR_TURN_RATE</code>].

; '''Can I know the heading of the enemy gun/radar?'''
: No.

; '''Can I specify the initial position of my bot?'''
: No. The bots are randomly placed in the field at the beginning of each round.

; '''How can I find more information about Robocode's internals?'''
: The true documentation is the source code. [https://github.com/robo-code/robocode Take a look].

: Tips for navigating through the Robocode codebase:
:* Robocode internally makes use of [http://picocontainer.com/ picocontainer] to provide [[wikipedia:Dependency Injection|dependency injection]].
:* The API methods are implemented in the [https://github.com/robo-code/robocode/blob/master/robocode.api/src/main/java/robocode/AdvancedRobot.java <code>AdvancedRobot</code>] and [https://github.com/robo-code/robocode/blob/master/robocode.api/src/main/java/robocode/Robot.java <code>Robot</code>] classes. They are wrappers around the [http://robocode.sourceforge.net/docs/robocode/robocode/robotinterfaces/peer/package-summary.html robot peer], which calls into the Robocode core. You can trace the flow of execution from there.
:* You can find a class' source file given its name through the [https://github.com/blog/793-introducing-the-file-finder GitHub File Finder], by pressing <code>t</code> anywhere in GitHub.
:* GitHub's [https://help.github.com/articles/searching-code/ repository code search] is also helpful.
:* Robocode's [https://github.com/robo-code/robocode/blob/master/versions.md version history] provides useful details about how the program evolved.

== Programming your robot ==
; '''What is the difference between the setXXX() (e.g. <code>setFire()</code>) and the XXX() (e.g. <code>fire()</code>) methods?'''
: Basically, the setXXX() methods just notify Robocode to take some action at the end of the turn. The XXX()-type methods end the turn when you call them, and they block your robot's thread until the command finishes. Unless you have a good reason, you should almost always use the setXXX() version when writing [[AdvancedRobot|AdvancedRobots]].

; '''How can I avoid my gun/radar turning when my bot turns?'''
: You can use <code>setAdjustGunForRobotTurn()</code>, <code> setAdjustRadarForGunTurn()</code>, and <code>setAdjustRadarForRobotTurn()</code> methods to control this. If you call <code>setAdjustGunForRobotTurn()</code> and <code> setAdjustRadarForGunTurn()</code>, you don't need to call <code>setAdjustRadarForRobotTurn()</code>.

; '''Why are there two functions for <code>getBearing()</code> for example - one in radians and one in degrees? Is there any performance gain if I use radians instead of degrees?'''
: There is no real advantage to using one or the other. Just use the one you prefer. Often, people start using degrees (just because they feel more comfortable with them) and later they switch to radians (because calculations are easier since you can use the built-in Java trigonometric functions). Just remember to use always radians or always degrees; mixing them up is not a good idea.

; '''I need to trace my bots actions and variables. I saw that everybody uses <code>out.println("...")</code>, but where is that printed?'''
: It prints to the [[Robocode/Robot Console|robot console]]. When you execute the battle, just click on the button on the right of the screen that shows the name of your robot to open its [[Robocode/Robot Console|console]].

; '''How do you get your radar to stay focused on a robot that you have defined as your target?'''
: You just turn the radar the other way around when you scan the bot. You lock your radar by not turning it 45 degrees, but only the arc needed to stay focused. See the [[Radar]] page for some example code.

; '''How can I know how many enemies are in the battle field?'''
: You can use the <code>getOthers()</code> method to know how many live enemies are in the battlefield.

; '''I'm trying to recognize an enemy/teammate from its name (using <code>e.getName()</code>) but the condition always fails. What's happening?'''
: Because of Java's funky way of interpreting references to Strings (not to mention a lack of operator overloading), you can't use an expression like <code>if (e.getName() == testname)</code> to check for equality. You have to use the <code>String.equals()</code> method, as in <code>if (e.getName().equals(testname))</code>.

; '''How do I keep data from round to round and battle to battle?'''
: The easiest way is to save data between rounds of a battle is to make the variables in the bot class static. Because Robocode uses a separate classloader for every robot, the variables will not conflict even when you have more than one copy of a robot in a battle. Note that this will save data between ''rounds'', not between ''battles''. To save between battles you will have to save to a file. The maximum allowed disk space for files is 200k. Look at the [[:Category:Robocode API|Robocode API]] for more details.

; '''I get the following message when I run my bot, and I don't know how to solve it.'''
<pre>
SYSTEM: You have made 10000 calls to getXX methods without calling execute()
SYSTEM: Robot disabled: Too many calls to getXX methods.
</pre>
: Robocode prevents you from calling functions like <code>getX()</code> or <code>getVelocity()</code> too many times during a single tick. So if you are using them in a long loop, it will raise this error. Actually, 95% of the time, this error is a symptom of an infinite loop in your bot. If you know you have a long-but-finite loop and you get this error, either just assign the values you want to use to a variable or use a [[RobotStatus]] object obtained from [[StatusEvent]].

; '''I'm using <code>bulletObject = setFireBullet(power)</code> to fire, and then I want to get the bullet coordinates. But when I try to print them using <code>System.out.println(bulletObject.getX() + bulletObject.getY())</code> I get an error. What's wrong?'''
: <code>setFireBullet()</code> creates a Bullet object, but the bullet doesn't actually leave your bots gun until the next tick, so you can't do <code>getX()</code> or <code>getY()</code> on the bullet until then. If you change it to <code>fireBullet()</code> you should be OK, because the function won't return until the bullet is in the air. If <code>fireBullet()</code> won't work for you, you'll have to devise another method of making sure that you don't do <code>getX()</code> and <code>getY()</code> on bullets until the turn after you fire. For example, you could store Bullets in an ArrayList, and print out their coordinates before you fire in your main loop, so that a given bullet will be added to the vector on one turn, but won't be accessed until the next turn when your main loop starts over. Alternatively, your bot can attempt to predict/simulate it's own location on the next tick, to know where the bullet will be created.

; '''I want to reverse my direction when my movement is about to finish. I use something like <code>if (getDistanceRemaining() < minimum)</code>, but the bot behaves in a strange way.'''
: The <code>getDistanceRemaining()</code> method (and in general all methods returning remaining movements of the body, gun, or radar) can return a positive or a negative value, depending on the direction of your movement. Use <code>if (Math.abs(getGetDistanceRemaining()) < minimum)</code> instead.

[[File:AbsoluteRelativeAngles.png|thumb|300px|Absolute and relative angles in Robocode]]
; '''What are the [http://robocode.sourceforge.net/docs/robocode/robocode/util/Utils.html <code>robocode.Utils</code> angle normalization methods]?'''
: In Robocode, relative angles (-180° to 180°) are commonly used as inputs to <code>setTurnGunRight()</code> and other such robot control methods. Normalizing them is often used as an optimization – for instance, there is no point of turning the gun 270° if you can turn it -90° instead; that saves 9 ticks. The method [http://robocode.sourceforge.net/docs/robocode/robocode/util/Utils.html#normalRelativeAngleDegrees(double) <code>Utils.normalRelativeAngleDegrees()</code>] is used to normalize relative angles. Similarly, absolute angles (0° to 360°) can be normalized with [http://robocode.sourceforge.net/docs/robocode/robocode/util/Utils.html#normalAbsoluteAngleDegrees(double) <code>Utils.normalAbsoluteAngleDegrees()</code>].

; '''My trigonometric calculations get very strange results. What is wrong?'''
: Normal trigonometry is counterclockwise (the angle increases to the left) but in Robocode it is clockwise (the angle increases to the right). It means that you cannot directly apply the normal trigonometric formulas to Robocode. Essentially, it means you must use <code>Math.sin()</code> where you would normally use <code>Math.cos()</code>, and <code>Math.cos()</code> where you would normally use <code>Math.sin()</code>.

; '''How do I find the absolute angle between two coordinates?'''
: <syntaxhighlight lang="java">double angle = Math.atan2(x2 - x1, y2 - y1);</syntaxhighlight>

; '''How do I calculate the distance between two coordinates?'''
: With this code (make sure to import <code>java.awt.geom.Point2D</code>):
: <syntaxhighlight lang="java">double distance = Point2D.distance(x1, y1, x2, y2);</syntaxhighlight>
: Alternatively, if you're doing this only to compare distances, <code>Point2D.distanceSq()</code> is a little faster as skips the square root calculation.

; '''How to I drive to a certain point?'''
: See the [[GoTo]] page for code examples.

; '''How do I do [some other thing that sounds incredibly basic]?'''
: Every one of the top bots has a general utility class somewhere in its code. Take a look.

== See also ==

{{RobocodeDocsList}}

[[Category:Robocode Documentation]]

Robocode/Eclipse/Create a Project

2019-05-29T19:37:39Z

FlemmingLarsen: /* New Project */

{{Youtube|3qOoDuGkwco|Creating an Eclipse Robocode Project}}

In order to build a [[Robocode]] robot in [http://www.eclipse.org/ Eclipse], we first have to create a '''Project''' to store them in. This page will assist you in setting that up.

== Creating a Project for your Robots ==
First, select File->New->Project in the menu.

[[Image:Eclipse-FileNewProject.png|Shows how to select a new project from the File menu in Eclipse]]

In the '''New Project''' dialog, select '''Java Project''' then click Next.

[[Image:Eclipse-NewProjectWizard.png|Shows a dialog for creating a new project by selecting a wizard]]

Type in a name for your project. A project can contain just one robot or many robots, so choose a name to suit your plans. Here we use the name '''MyRobots''' as the name for the new project. When you have written the name of the new project then click '''Next'''. <span style="color:red">''But do not click '''Finish''' yet!''</span>

[[Image:Eclipse-NewJavaProject.png|Shows a dialog for creating a new Java project where the user must type in a name for the new project]]

=== Oops! I clicked '''Finish'''. What to do? ===
If you clicked '''Finish''' by mistake, you can find the rest of the screens shown by right-clicking on the project named '''MyRobots''', then select '''Properties''', and then select '''Java Build Path'''.

== New Project ==
Select the '''Libraries''' tab, then click on '''Add External JARs''':

[[Image:Eclipse-NewProjectAddExtJars.png|Shows that the "Libraries" tab must be selected and then the "Add External Jars..." on the pane with Java Settings in the New Java Project dialog]]

Browse to the robocode directory, select the '''libs''' directory and then click the '''Open'''.

[[Image:Eclipse-JarSelection.png|Shows the JAR Selection dialog where the user must first select the libs dir within the Robocode root dir and press the "Open" button]]

Next, select the '''robocode.jar''' and then click the '''Open'''.

[[Image:Eclipse-JarSelection2.png|Shows the JAR Selection dialog where the user must secondly select the robocode.jar file within the libs dir and press the "Open" button]]

Now you must select the '''Javadoc location: (None)''' under '''robocode.jar''' and click '''Edit...'''

[[Image:Eclipse-NewProjectEditJavadocLocation.png|Shows that the "Javadoc location: (None)" line under "robocode.jar" must be selected and then the "Edit..." in the New Java Project dialog]]

Type in (or browse to) the path for robocode.jar again. Optionally, enter the location of Robocode's Javadocs. The window should now look like this:

[[Image:Eclipse-RobocodeJavadocURL.png|Shows a dialog where the user must specify the URL of the Javadoc location path of Robocode]]

Click '''OK''', then click '''Finish''' to build your project.

Congratulations! Your new project is ready. :-)

== Note about module-info.java ==
Please note that the newest versions of Eclipse will ask if you want to create a module-info.java file.
If you get this question, you should select "Don't create".

'''If you by mistake create a module-info.java, then you should make sure to delete it to avoid compiler and classpath issues.''' The module-info.java is not used for Robocode packages.

== References ==
* [http://www.eclipse.org/ Eclipse.org - Eclipse home page]
* [http://www.eclipse.org/downloads/ Eclipse Downloads]
* [http://download.eclipse.org/eclipse/downloads/ Eclipse project downloads - latest releases]

== See also ==

=== Using Eclipse IDE ===
* [[Robocode/Eclipse|Using Eclipse as IDE]]
* [[Robocode/Add_a_Robot_Project|Add robot project from an IDE into Robocode]]
* [[Robocode/Eclipse/Create_a_Robot|Creating a robot in Eclipse]]
* [[Robocode/Running from Eclipse|Running your robot from Eclipse]]
* [[Robocode/Eclipse/Debugging Robot|Debugging your robot with Eclipse]]

=== Robot API ===
* [http://robocode.sourceforge.net/docs/robocode/ Robot API]

=== Tutorials ===
* [[Robocode/System Requirements|System Requirements for Robocode]]
* [[Robocode/Download|How to download and install Robocode]]
* [[Robocode/Robot Anatomy|The anatomy of a robot]]
* [[Robocode/Getting Started|Getting started with Robocode]]
* [[Robocode/My First Robot|My First Robot Tutorial]]
* [[Robocode/Game Physics|Robocode Game Physics]]
* [[Robocode/Scoring|Scoring in Robocode]]
* [[Robocode/Robot Console|Using the robot console]]
* [[Robocode/Downloading_Robots|Downloading other robots]]
* [[Robocode/Learning from Robots|Learning from other robots]]
* [[Robocode/Package Robot|Package your robot]]
* [[Robocode/FAQ|Frequently Asked Questions (FAQ)]]
* [[Robocode/Articles|Articles about Robocode]]
* [[Robocode/Console Usage|Starting Robocode from the command line]]
* [[Robocode/Graphical_Debugging|Graphical debugging]]

=== News and Releases ===
* [http://sourceforge.net/export/rss2_project.php?group_id=37202 RSS Feeds for the Robocode project]
* [http://sourceforge.net/project/showfiles.php?group_id=37202&package_id=29609 Robocode file releases]

=== Home pages ===
* [http://robocode.sourceforge.net/ Classic homepage]
* [http://sourceforge.net/projects/robocode Robocode project at SourceForge]
* [http://robocoderepository.com/ Robocode Repository]
* [[wikipedia:Robocode|Wikipediaentry for Robocode]]

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

Thread:Talk:RoboRumble/Upgrade client version/reply (33)

2018-11-06T22:03:56Z

FlemmingLarsen: Reply to Upgrade client version

Your pull request has now been merged and I have assembled and put a beta version here:
https://robocode.sourceforge.io/files/robocode-1.9.3.4-Beta-setup.jar

If you are satisfied with this version, I will make the release. :-)

Thread:Talk:RoboRumble/Upgrade client version/reply (30)

2018-10-28T19:42:36Z

FlemmingLarsen: Reply to Upgrade client version

Codesize 1.2 for Java 7, 8, 9 (Experimental) is ready.

Do we need to fix other stuff for RoboRumble before I make another release?

Robocode/Developers Guide for building Robocode

2018-10-19T23:51:40Z

FlemmingLarsen: /* How to build distribution files? */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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

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:

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

The URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:42:50Z

FlemmingLarsen: /* Getting sources from GitHub */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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

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:

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

The URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:42:06Z

FlemmingLarsen: /* Checking out sources from GitHub */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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

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:

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

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:34:02Z

FlemmingLarsen: /* Required technical skills? */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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

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:

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.

=== Checking out sources from GitHub ===

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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:25:52Z

FlemmingLarsen: /* Required technical skills? */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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

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:

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

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:12:00Z

FlemmingLarsen: /* Required technical skills? */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* 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])

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.

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:05:44Z

FlemmingLarsen: /* Setting up Java Environment Variables */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T23:05:12Z

FlemmingLarsen: /* Setting up Java Environment Variables */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T22:59:41Z

FlemmingLarsen: /* Setting up Java Environment Variables */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

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

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.8.0_162/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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 Notes from Oracle:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T22:57:55Z

FlemmingLarsen: /* Setting up Java Environment Variables */

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 [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].

=== Requirements ===

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

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

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

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. [https://docs.oracle.com/cd/E19182-01/821-0917/inst_jdk_javahome_t/index.html 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 <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.

'''Windows:'''
* JAVA_HOME is set to e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.6.0_45"</code>.
* PATH is extended, e.g. to <code>PATH=%JAVA_HOME%\bin;PATH</code>.

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.6.0_45/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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 Oracle JDK here:

'''Installation Notes from Oracle:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2018-10-19T22:51:00Z

FlemmingLarsen: /* Installing the JDK */

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 [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].

=== Requirements ===

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

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

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

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

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

'''Windows:'''
* JAVA_HOME is set to e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.6.0_45"</code>.
* PATH is extended, e.g. to <code>PATH=%JAVA_HOME%\bin;PATH</code>.

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.6.0_45/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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 Oracle JDK here:

'''Installation Notes from Oracle:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Thread:Talk:RoboRumble/Upgrade client version/reply (28)

2018-10-19T17:59:53Z

FlemmingLarsen: Reply to Upgrade client version

I will definitely have to fix codesize as I have not touched it for many years. :O

Also notice that it will be faster to write to me a mail at fnl (at) users.sourceforge.net in order to have me fix as many issues related to RoboRumble as possible (this has a high priority to me). Just tell me to look on this discussion, if all details are already provided. This way you'll not have to wait for me updating Robocode, Codesize, RoboRumble etc. :-)
And thank you for providing me with patches for RoboRumble. It is a great help to all of us.

Robocode/Developers Guide for building Robocode

2018-10-19T17:42:15Z

FlemmingLarsen: /* Requirements */

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 [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].

=== Requirements ===

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

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

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

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 in Oracle's Java SE 6, and requires the Java Developer Kit ('''JDK''') 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.

The JDK 6 is used for the building official releases for Robocode even when this old version 6 has entered it's End-of-Life (EOL). The reason being that Java SE 6 is the minimum requirement when end-users needs to run Robocode, and due to the fact that the current build system of Robocode is known to cause problems with building Robocode with newer JDK versions (e.g. version 7 and 8). If you are unhappy about that, you are welcome to update the build system (including the part required for building the .NET plug-in for Robocode). ;-)

If you just want to play with the sources (without using the build scripts for Robocode), you could use a newer JDK 7+ if you want to, e.g. building Robocode inside the Eclipse IDE. 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. Another problem is that the .NET plug-in for Robocode needs to make use of the build scripts for Robocode and also requires additional Windows-specific tools to be installed on your system.

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

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

'''Windows:'''
* JAVA_HOME is set to e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.6.0_45"</code>.
* PATH is extended, e.g. to <code>PATH=%JAVA_HOME%\bin;PATH</code>.

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.6.0_45/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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 Oracle JDK here:

'''Installation Notes from Oracle:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Robocode/Developers Guide for building Robocode

2015-05-30T20:54:44Z

FlemmingLarsen: Major update from JDK 5 til JDK 6 and removal of EGit stuff

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 [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].

=== Requirements ===

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

* Oracle JDK 6 ([http://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase6-419409.html#jdk-6u45-oth-JPR old archive]). Note that only version 6 will work. Newer versions are not supported (yet)
* Source files for Robocode ([https://github.com/robo-code/robocode on GitHub])
* 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 [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.

==== Installing the JDK ====

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

The JDK 6 is used for the building official releases for Robocode even when this old version 6 has entered it's End-of-Life (EOL). The reason being that Java SE 6 is the minimum requirement when end-users needs to run Robocode, and due to the fact that the current build system of Robocode is known to cause problems with building Robocode with newer JDK versions (e.g. version 7 and 8). If you are unhappy about that, you are welcome to update the build system (including the part required for building the .NET plug-in for Robocode). ;-)

If you just want to play with the sources (without using the build scripts for Robocode), you could use a newer JDK 7+ if you want to, e.g. building Robocode inside the Eclipse IDE. 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. Another problem is that the .NET plug-in for Robocode needs to make use of the build scripts for Robocode and also requires additional Windows-specific tools to be installed on your system.

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

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

'''Windows:'''
* JAVA_HOME is set to e.g. <code>JAVA_HOME="C:\Program Files\Java\jdk1.6.0_45"</code>.
* PATH is extended, e.g. to <code>PATH=%JAVA_HOME%\bin;PATH</code>.

'''Linux / *nix:'''
* JAVA_HOME is set by e.g. <code>export JAVA_HOME=/usr/java/jdk1.6.0_45/bin/java</code>. (Bash)
* PATH is extended, e.g. by <code>export PATH=$JAVA_HOME/bin:$PATH</code>. (Bash)

'''Mac OS X:'''
* 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>.

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 Oracle JDK here:

'''Installation Notes from Oracle:'''
* [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.

==== Required technical skills? ====

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

* Eclipse IDE ([http://www.vogella.com/articles/Eclipse/article.html Tutorial])
* 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])

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

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.

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 [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 URL of the sources at GitHub is:
[https://github.com/robo-code/robocode.git 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.

=== 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 ([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.

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.

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

==== 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. <code>C:/Users/Flemming/.m2/repository</code> (Windows) or <code>/home/fnl/.m2/repository</code> (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...
# 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.

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

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

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

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

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

Other JVM Languages

2015-03-25T23:00:16Z

FlemmingLarsen: /* Clojure */

Robocode is not limited to Java robots! Since Robocode allows you to load classes on the CLASSPATH, you can code robots in any language that can produce compiled CLASS files. Support for languages which don't have a compiler will require changes to Robocode which nobody has yet volunteered to implement.

The easiest way to add a language's runtime to Robocode's CLASSPATH is to edit the starter script. Make sure you add the path to your compiled files under the '''Development Options.'''

==[http://www.scala-lang.org/ Scala]==
You need to add <code>scala-library.jar</code> to Robocode's CLASSPATH:
<pre>
java -Xmx512M -Dsun.io.useCanonCaches=false -cp libs/robocode.jar;_SCALA_HOME_/lib/scala-library.jar robocode.Robocode %*
</pre>

You also need to disable security, if your Scala program does anything that needs to actually access the Scala libraries.

Once that is done, coding robots in Scala is like coding in Java, but nicer:
<syntaxhighlight>
// ScalaDemo.scala
package wiki

import robocode._
import robocode.util.Utils

/*
A small demo to test robot coding in Scala.
*/
class ScalaDemo extends AdvancedRobot {

// Main thread of robot
override def run {
setAdjustGunForRobotTurn(true)
while (true) {
// If we're not going anywhere, move randomly around battlefield
if (Math.abs(getDistanceRemaining) < Rules.MAX_VELOCITY
&& Math.abs(getTurnRemaining) < Rules.MAX_TURN_RATE)
{
setAhead((Math.random*2-1)*100)
setTurnRight(Math.random*90-45)
}
// Tell RADAR to spin
if (getRadarTurnRemaining == 0)
setTurnRadarRightRadians(4)
// Carry out pending actions
execute
}
}

// Picked up a robot on RADAR
override def onScannedRobot(e : ScannedRobotEvent) {
// Absolute bearing to detected robot
val absBearing = e.getBearingRadians + getHeadingRadians

// Tell RADAR to paint detected robot
setTurnRadarRightRadians(3*Utils.normalRelativeAngle(
absBearing - getRadarHeadingRadians ))

// Tell gun to point at detected robot
setTurnGunRightRadians(Utils.normalRelativeAngle(
absBearing - getGunHeadingRadians ))

// Tell robot to shoot with power 2
setFire(2)
}

// Robot ran into a wall
override def onHitWall(e : HitWallEvent) {
// Turn in opposite direction to wall
setTurnRightRadians(Utils.normalRelativeAngle(
e.getBearingRadians + Math.Pi))
}
}
</syntaxhighlight>

Compile like you would in Java:

<pre>
scalac -cp _PATH_TO_ROBOCODE_/libs/robocode.jar ScalaDemo.scala
</pre>

==[http://mirah.org/ Mirah]==

Mirah compiles to java bytecode with no runtime dependency, so the compiled .class files run in Robocode.

Here is a very basic Mirah bot:

<pre>
package mirah

import robocode.AdvancedRobot

class MirahBot < AdvancedRobot

def initialize
puts 'constructor'
end

def run
setAdjustGunForRobotTurn(true)
while true do
if (getRadarTurnRemaining == 0)
setTurnRadarLeftRadians(2*Math.PI)
end
execute
end
end

end
</pre>

Compile using the Mirah compile, and include like a regular Java robot.

==[http://clojure.org/ Clojure]==
Coding robots in Clojure can be frustrating. You have to compile your code, but you don't get many of the benefits of using a compiler. For example, calls to non-existent methods are not caught until runtime. Typos in rarely run code can unexpectedly disable your robot (unless you use type hints everywhere and <code>(set! *warn-on-reflection* true)</code>, which is beyond the scope of this introduction).

First, you need to add <code>clojure.jar</code> to Robocode's CLASSPATH. You also have to disable the security manager (by passing <code>-DNOSECURITY=true</code> on the Robocode command line) or your robot will be disabled for trying to read the Clojure JAR which is outside its root directory.

<pre>
java -Xmx512M -Dsun.io.useCanonCaches=false -DNOSECURITY=true -cp libs/robocode.jar;_CLOJURE_HOME_/clojure.jar robocode.Robocode %*
</pre>

Note that the ';' sign must be replaced with ':' on a Unix-like OS, e.g. on Linux and Mac OS X.

A sample clojure robot:

<pre>
// ClojureDemo.clj
(ns wiki.ClojureDemo
(:gen-class :extends robocode.AdvancedRobot))

; Private declarations
(declare normalise)

(defn -run [robot]
(doto robot
(.setAdjustRadarForGunTurn true)
(.setAdjustRadarForRobotTurn true)
(.setAdjustGunForRobotTurn true))
(loop [r robot]
(.setAhead r 30)
(.setTurnRightRadians r 1)
(when (= 0 (.getRadarTurnRemainingRadians r))
(.setTurnRadarRightRadians r 4))
(.execute r)
(recur r)))

(defn -onScannedRobot [robot event]
(.setTurnGunRightRadians
robot (normalise (- (+ (.getBearingRadians event) (.getHeadingRadians robot))
(.getGunHeadingRadians robot))))

(when (< (Math/abs (normalise (.getGunTurnRemainingRadians robot)))
robocode.Rules/GUN_TURN_RATE)
(.setFire robot 2))
(.setTurnRadarRightRadians
robot
(* (normalise (- (+ (.getBearingRadians event) (.getHeadingRadians robot))
(.getRadarHeadingRadians robot)))
1.9)))

(defn- normalise [angle]
(robocode.util.Utils/normalRelativeAngle angle))
</pre>

Since one of the oft-touted features of LISPs (of which Clojure is one) is being so dynamic, the compiler is rather unpleasant to use. You have to follow all the following steps, or you might encounter errors:

1. Put your source code in a folder called '''src'''. Files in this directory must follow the pattern <code>src/PACKAGENAME/CLASSNAME.clj</code> or the compiler won't be able to find them.

2. Create a directory named '''classes''' next to your ''src'' directory. This is where compiled files will be put, and must exist before the compiler will agree to do anything.

3. You have to pass the package qualified name of every class you want to compile to the compiler. Given a class named <code>wiki.ClojureDemo</code>, the compiler will try to read <code>src/wiki/ClojureDemo.clj</code> to find it.

The command to compile the demo bot is:

<pre>
java -cp _CLOJURE_HOME_/clojure.jar -Dclojure.compile.path=classes clojure.lang.Compile wiki.ClojureDemo
</pre>

Note that <code>robocode.jar</code> was not on the compiler's CLASSPATH. That is how dynamic Clojure is.

If you plan to use multiple classes, using the compiler can become rather tedious. Below is an [http://ant.apache.org/ Apache Ant] script to compile all the files in the <code>src</code> sub-directory:

<pre>
<project name="robocode-robots" default="compile">

<property name="clojure.jar"
location="_PATH_TO_CLOJURE_/clojure.jar" />
<property name="robocode.jar"
location="_PATH_TO_ROBOCODE_/robocode.jar" />


<property name="src" location="src" />

<property name="build" location="classes" />

<target name="compile" description="Compile robots">
<mkdir dir="${build}" />

<pathconvert pathsep=" " property="compile.namespaces">
<fileset dir="${src}" includes="**/*.clj" />
<chainedmapper>

<packagemapper from="${src}\*.clj" to="*" />
<filtermapper>

<replacestring from="_" to="-" />
</filtermapper>
</chainedmapper>
</pathconvert>

<java classname="clojure.lang.Compile">
<classpath>
<path location="${src}" />
<path location="${build}" />
<path location="${clojure.jar}" />
<path location="${robocode.jar}" />
</classpath>
<sysproperty key="clojure.compile.path" value="${build}" />
<arg line="${compile.namespaces}" />
</java>
</target>

<target name="clean" description="Remove compiled files">
<delete dir="${build}" />
</target>
</project>
</pre>

Thread:Talk:Gilgalad/Minibot?/reply (22)

2014-09-15T19:13:19Z