JMRI: Building with NetBeans
- Introduction
- Getting and Installing NetBeans
- Checking out code
- Updating the code from SVN
- Building and running JMRI
- Making a Jar File
- Making a Patch File
- Making a release package for Windows using NSIS
- Running FindBugs
- NetBeans and compiling individual files
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
- Download NetBeans 7.2 (The Java SE version is fine) from
www.netbeans.org
(If you don't yet have Java Development Kit 6.0 (JDK) installed on your system, download a JDK-NetBeans bundle - on the NetBeans download page, look for a link similar to "JDK with NetBeans IDE Java SE bundle".) - Run the NetBeans package installer
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.
- Repository URL: http://svn.code.sf.net/p/jmri/code/
- User: leave empty
- Password: leave empty
- [Next >]

- Repository Folder(s): trunk/jmri
- Repository Revision: leave set for HEAD
- Skip "jmri" and checkout only its content: leave unchecked
- Export a clean directory tree from the repository: leave unchecked
- Local Folder: pick some place on your hard drive...
- Scan for NetBeans Projects after Checkout: ensure checked
- [Finish]

[Window]->[Output]->[Output] shows SVN activity log window...
- Wait a for the SVN checkout to complete. This SVN checkout moves over 100 MBytes of code, help files, .pdf files, tool configuration files and other information.
- A popup will display stating that 2 projects were checked out and asking if you want to open the projects.
- [Open Project...]
- In the Open Projects popup, choose JMRI
- [Open]
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.
- Repository URL: svn+ssh://svn.code.sf.net/p/jmri/code/trunk/jmri
- User: <your sourceforge user name>
- Password: <your sourceforge password>
- Port Number: leave set at 22
- Identity File: leave blank
- Passphrase: leave blank
- Save Username and Password: check or un-check to suit your needs
- Proxy Configuration button: Set proxy information if required for your network setup
- [Next >]

- Repository Folder(s): trunk/jmri
Note that you may [Browse] to another part of the SVN repository directory structure if you desire to check out only a part of the JMRI repository.
- Repository Revision: leave set for HEAD
Note that you may [Browse] the tags, branches, or trunk of the SVN repository to check out a specific version of JMRI. You may also [Search] by date to find and check out a version of JMRI by date.
- Skip "jmri" and checkout only its content: leave unchecked
- Export a clean directory tree from the repository: leave unchecked
- Local Folder: pick some place on your hard drive...
- Prefer old Subversion 1.6 Format: leave unchecked
- Scan for NetBeans Projects after Checkout: ensure checked
- [Finish]

[Window]->[Output]->[Output] shows SVN activity log window...
- Wait a for the SVN checkout to complete. This SVN checkout moves over 100 MBytes of code, help files, .pdf files, tool configuration files and other information.
- A popup will display stating that 2 projects were checked out and asking if you want to open the projects.
- [Open Project...]
- In the Open Projects popup, choose JMRI
- [Open]
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.
- Run -> Run Project (JMRI) will compile and invoke DecoderPro
- You can choose other targets (i.e. PanelPro...) by changing [File]->[Project Properties (JMRI)]->[Build and Run]->[Run Project]
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":
- From the [Team] menu, select "Export Diff Patch ..."
- A file browser will open; enter a new file name in your preferred location and hit "Save" or "Open", depending on what the dialog shows.
- After it finishes calculating the diffs, the file you selected will contain the patches, along with an information header.
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