Skip to main content

Info on JMRI:
Development tools
Structure
Techniques and Standards
How To
Functional Info
Background Info

JMRI: Building with NetBeans

See Also

Introduction

NetBeans 7.2 (available at www.netbeans.org) makes a great platform for working with JMRI. The JMRI code is setup to work with NetBeans with almost no additional setup. (The description below is accurate for the Windows version of NetBeans 7.2. NetBeans is supposed to be identical across platforms, but this hasn't been checked on anything else).

NetBeans is a very powerful Integrated Development Environment (IDE), which can make working with the JMRI code pretty easy. But it takes a little getting used to, and reading the tutorials on the NetBeans 7.2 web site will be helpful.

Getting and Installing NetBeans

Many Linux distributions have NetBeans available in their software repositories - search your package manager for NetBeans.

Checking out code

Subversion (also known as SVN) provides version control for projects hosted at sourceforge.net, such as the JMRI project. NetBeans provides built-in support for SVN functionality. NetBeans SVN support may be configured in either of two ways, depending on how the user wishes to interact with the SVN repository.

Users who wish to get a copy of the code, but do not wish to make commits (i.e. changes) to the JMRI SVN repository at sourceforge.net may configure NetBeans SVN to access the repository in a read-only mode. These users do not need an account at sourceforge.net. Once a NetBeans project is configured for this "read-only" SVN access of the JMRI code repository, it will be difficult to later "commit" changed code to the JMRI repository. Instructions to check out a copy of JMRI source code without an easy ability to update the JMRI repository are found below at Configuring NetBeans SVN to allow only Check-out.

Users who wish to get a copy of the code, and who do wish to be able to make commits (i.e. changes) to the JMRI SVN repository at sourceforge.net may configure NetBeans SVN to access the repository in a read-write mode. These users require an account at sourceforge.net, and this account information is used every time NetBeans/Subversion is used to access the JMRI SVN repository. Instructions to check out a copy of JMRI source code without an easy ability to update the JMRI repository are found below at Configuring NetBeans SVN to allow both Check-out and Commit

Configuring NetBeans SVN to allow only Check-out

The easiest way to get the initial copy of the code (without the ability to commit changes to the JMRI SVN repository), as well as the files for all available translations of the help pages, is to check it out using NetBeans' integrated SVN, without using a personal sourceforge.net account . Once you've done that, NetBeans will automatically use it. When using this process, it will not be possible to submit changes to the SVN repository. If you have a sourceforge.net login, and are a member of the sourceforge.net JMRI project, then you will want to use a different configuration in NetBeans. See Configuring NetBeans SVN to allow both Check-out and Commit

Here's how:

Start NetBeans and do the following steps. Text in brackets [] are menu items to be selected or buttons to be pressed. Text in this font should be typed into NetBeans exactly as written. This font denotes explanations and stage directions to follow.

[Team]->[Subversion]->[Checkout]
[Window]->[Output]->[Output] shows SVN activity log window...

Configuring NetBeans SVN to allow both Check-out and Commit

If you have a sourceforge.net account and are a member of the sourceforge.net JMRI project, and you wish to be able to check out and submit changes to the JMRI SVN repository at sourceforge.net, then it is necessary to follow a different process than listed above.

Start NetBeans and perform the steps shown below. In the description, text in brackets [] are menu items to be selected or buttons to be pressed. Text in this font should be typed into NetBeans exactly as written. Text in this font represents your sourceforge.net login information. This font denotes explanations and stage directions to follow.

[Team]->[Subversion]->[Checkout]
[Window]->[Output]->[Output] shows SVN activity log window...

Updating the code from SVN

From time to time, you can update your local copy of the code to match the current "head" of the sourceforge.net JMRI SVN repository contents. To do this, use the NetBeans [Team]->[Update] menu choice.

You may also update a single file or the contents of a folder, by right-clicking on an item in the "Files" window, then selecting [Subversion]->[Update].

Building and running JMRI

To build and run DecoderPro, all you have to do is select "Run Project (JMRI)" from the Run menu, or click the Run icon in the tool bar.

If you want to run the program under the NetBeans debugger, first set JMRI to be the Main project via [Run]->[Set Main Project]->[JMRI] then select "Debug Main Project" from the "Debug" menu.

Making a Jar File

Most of the code in a normal JMRI installation lives in a file called jmri.jar. If you want to replace this with your updated version, you need to create a new jmri.jar file from your modified code.

To do this, ctrl-click (or right-click) on the name of the "JMRI" project in the "Projects" window. This will open a pop-up menu, on which you'll find "Make Jar File". Select that, and a new jmri.jar file will be produced in the project's main directory.

Alternately, from the "Files" window, right-click on the build.xml file, and select "Run Target", then "jar".

Making a Patch File

A "diff patch file" is an easy way to gather up all your changes, even if they span multiple files, into one file that you can then send to us. It's also easy to merge in with the rest of the code, so we greatly prefer that you use this. If you have checked-out the SVN repository using the first method shown above (i.e. without using a sourceforge.net user name and password), this is the best way to collect any code changes you have for submission to the JMRI developer's team for inclusion in a future JMRI release.

To create the "diff patch file":

Making a release package for Windows using NSIS

It is possible for NetBeans users to create a release package for use on the Windows platform. This requires installation of the Nullsoft Scriptable Install System (NSIS), which can be downloaded from the NSIS project web site on SourceForge.

Once NSIS is installed on the computer, it is necessary to create a file called local.properties in the same directory as JMRI's build.xml file. This file is specifically not checked in via SVN, so that your machine-specific tool installation paths are not checked in to SVN. Create the file, and add a variable definition with the correct path to the directory which includes the NSIS executable, such as:

nsis.home=C:/Program Files (x86)/NSIS

or

nsis.home=/opt/nsis/nsis-2.46/

If you will be installing a "findbugs" tool, you will also define findbugs.home in this file. You may also define several other machine-specific and user-specific information as described in various locations in the build.xml file.

With the NSIS package installed to your computer, and build.xml properly modified, the Windows package may be created by running the "package-windows" ant target in build.xml.

Running FindBugs

The FindBugs tool is a static code analysis tool which examines JAVA source code for common coding issues. Installation of a FindBugs tool allows an ant task defined in build.xml to run FindBugs analysis across all of the JAVA source code in JMRI.

It appears that the build.xml file is not configured to allow a NetBeans FindBugs "plugin" to run analysis on the JMRI code except on a one-file-at- a-time basis. As such, it seems advisable to download and install the appropriate stand-alone FindBugs tool for your operating system. FindBugs downloads may be found at the FindBugs web site.

Once you have the FindBugs tool installed, you must provide a path to the directory containing the executable for use by the build.xml ant file. If necessary, create the local.properties file in the same directory as the JMRI build.xml file. In the local.properties file, add the variable findbugs.home with a path to the findbugs executable, such as:

findbugs.home=C:/findbugs-1.3.8

or

findbugs.home=/opt/findbugs-1.3.8

To run the FindBugs tool on JMRI code, execute the ant target "findbugs" which is defined in build.xml. Within NetBeans this can be accomplished by right-clicking build.xml in the "Files" pane and "Run"ing the "findbugs" target. When FindBugs completes, the NetBeans Output window will show the path to a report file in HTML format. Open that file with a browser to review the FindBugs results.

NetBeans and compiling individual files

The NetBeans IDE shows icons to the side of each object in the Projects window, and to the side of each file in the Files window. These icons can reflect the status of each item, including local change and proper compilation status.

At this time, the files (in the project's nbproject/ directory) which control how NetBeans performs individual file compilation, do not properly reflect all of the requirements of the JMRI project. Until these files are properly updated, the error icons will persist within the JMRI project. These error icons do not affect the ability of NetBeans to compile the source files using the Ant tasks defined in the project's build.xml file.

Building the JMRI .jar file, and executing a JMRI tool from within NetBeans is generally done via Ant tasks, which are defined in the project's build.xml file. JMRI's developers have generally kept this file up-to-date, so building the JMRI .jar file, and executing a JMRI tool from within NetBeans generally does not suffer from the shortcomings of the configuration information found in the files in the project's nbproject/ directory.

See Also

The NetBeans Integrated Development Environment web site

The Apache Subversion project web site

The NSIS project web site

The FindBugs web site