JMRI: Building with JBuilder

Although JBuilder has been used by JMRI developers in the past, it is no longer recommended. NetBeans, XCode, Eclipse, or even just bare Ant is now a better solution.

The Personal Edition of JBuilder is available for free download at http://www.borland.com/jbuilder/personal/.

You may have trouble running an existing copy of JMRI or DecoderPro after installing JBuilder. The JBuilder install adds another version of Java and sets it as current. When a Java program starts, e.g. DecoderPro, it looks for it's libraries in the current Java install. So the files (from the original DecoderPro install) are still there, but it's looking in a different place now, and can't run. Reinstalling DecoderPro will put the libraries in the current Java install, and should fix this.

Once you have JBuilder installed, start it up once to go through the licensing procedure. The steps to get a working project are then:

Create a "project" directory.
In the project directory, do a CVS checkout of the "jbuilder" module from our repository (see above). This will create a "java" subdirectory where the JBuilder IDE will run, and load it with source, tests and resources. It will also create and populate directories for xml and libraries in the project directory.
The personal edition of JBuilder insists that libraries be in specific place. Because that place changes from computer to computer, we haven't been able to create an installer smart enough to handle it. You have to do the following steps manually, but just once per computer (if you check out a new copy of the source, this should still be ok):
- Find the .jbuilder directory. This is probably in or near your "home" directory. On a linux or MacOS X system, look in "~". On Windows, you should search for it.
- In the java directory that you just checked out, there's a "lib" directory. Copy that "lib" directory and its contents to the .jbuilder directory.
- Check to make sure that the lib directory in the .jbuilder directory contains the files README, Serialio.jar, collections.jar, lib/comm.jar, lib/crimson.jar, lib/jdom-jdk11.jar, lib/junit.jar, lib/log4j.jar, and lib/security.policy
- In the java directory that you just checked out, there's a JMRILibraries.library file. Copy that file to the .jbuilder directory.
Change to the newly created java subdirectory. Start JBuilder with the jmri.jpx file you'll find there.
Click run, and sit back to watch it go.

JBuilder can become confused, in which case you'll have problems with seemingly missing files, wrong class names, etc. When that happens, remove the "classes" folder from the project's "java" directory.

The Personal Edition of JBuilder does not come with the ability to make .jar files. (A .jar file is a "Java Archive", essentially a machine-readable library. For example, the JMRI code is compiled into the jmri.jar file for execution.) You can run the program from within JBuilder, but if you want to make a new jmri.jar file to update a stand-alone copy, you need to:

Change to the java/classes directory
From a Windows command prompt, execute the command
```
      jar cf ..\jmri.jar jmri resources apps
```
(That 3rd item would be ../jmri.jar on Linux or MacOS X)
This created a new "jmri.jar" file in the "java" directory of the project. Copy or move it to an existing JMRI directory and start the program, which should then be using your new code.

Note 1: The "jar" command is installed as part of a Java Software Development Kit (SDK), including the one installed with JBuilder. If the jar command isn't found, search for a jar.exe file (any one will do, they're all the same for this purpose) and enter the entire pathname, e.g.

   C:\jdk1.3.1_04\bin\jar ..\jmri.jar jmri resources apps

Note 2: If you leave a "jmri.jar" file in the java\classes directory by accident, it will be used instead of the class outputs of JBuilder. This will have the effect of "I compiled my change, but it's not being used!" because the older version of a class in that jmri.jar file will be used instead of the new .class file you created by recompiling. Hence the recommendation that you create the new jmri.jar file one level up by specifying "..\jmri.jar" in the command.