Configuring Netbeans IDE for FreeCol

* this page is still in draft status *

The following tutorial will help to configure a Netbeans IDE project to compile and run the game FreeCol. Though it was written specifically for this project it can be used as a visual tutorial to set up any project based on an existing ant build script.

The tutorial is intended for Netbeans IDE only, if you use any other tool, like Eclipse, the instructions listed here won't help you much.

Before we start you need to understand that, though you'll be able to use Netbeans IDE to write and run your code, some features of the IDE will not be available and some others may be annoying to use. This will depend heavily on the type of code you have and the structure you used to set up your project before importing it to the IDE.

FreeCol project structure is different from most of other projects I've seen, a particular difference is the existence of important files inside the build folder, instead of being on the src folder, some files exist only inside build and are not copied with the running of the build target. Therefor don't delete the build folder, if you use any special script or tool that needs or expects build to be deletable, please consider disabling it.

A assume you have already checked out the source, either main or any given branch you will be using, if you haven't please take a few moments to do so. You can find instructions on the FreeCol's documentation page and if you need some help with Subversion maybe this tutorial can help.

Start by creating a new project and choosing the Java Project with Existing Ant Script type.

Define the project's name and location.
The first fields refer to the location of the build script and the project files, like source files, libraries and all other needed files. It will be the location into which you downloaded FreeCol. The second pair are the location of the new project that is going to be created. This includes only IDE settings and some configuration files.
You can put the new project inside your working copy if you remember not to commit it, it will make things easier to find and use. But it really up to you, both location need not be the same.

We now need to connect our ant targets, defined in the build script, with the default ones used by the IDE. You can change this later and even add a few more.
We add a non existing target in the Run Project option, I named it run but you can use any other name you want, but remember that name because it is going the be used later when we define the ant target.

Add the source and test folders where the source files are located and continue to the next screen.

If you want to use code completion add the sources here.
You'll need to define a set of paths for each package. If you look at the screenshot you'll see that I added the folder where the source files exist to be the source of code completion for every file under the src package.

Just press finish and after a few moments the IDE will show you a list of all packages and files it found. Note that it may take a few moments for the IDE to see all files.

When we right click the project all ant targets that we defined earlier are available.
If we select the run target it will fail as there is no target named 'run in our build script.

Before we can use all ant targets we need to create the missing run target. Open the build.xml file in the IDE and append the following code just before the last closing tag.

    <target name="run" depends="package" description="Runs the game">
        <java jar="FreeCol.jar" fork="true">
            <jvmarg value="-Xmx128m" />
        </java>
    </target>

You can add this code anywhere in the file as long as it's inside the root tag, '<project>, and outside any <target> tag.

If you need to change the names of the standard target, right click the project name and choose the project properties option at the bottom.
You can add more ant targets to the context menu. All standard targets define in step 3 are available in the menus and keyboard shortcuts, the custom targets added afterwards are only available in the context menu accessible by right clicking the project item in the tree.

Note:
The little red icons that indicate an error in the code will not go away :), this is due to the IDE not knowing where some libraries are at coding time, but that won't be a problem because compilation is achieved from our own build script, if there are no errors in the code, the build will succeed as the script knows what and where those libraries are.