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

JMRI: Technical Info

You don't need to work with your own copy of the JMRI source code, compilers, etc if you just want to run the programs. You can download completely built copies via the downloads page. But if you'd like to play with the code, or get a copy of the program that contains updates since the last downloadable version was published, this section of the web site will help you get started.

Technical background info on the JMRI project

JMRI is intended as a jumping-off point for hobbyists who want to control their layouts from a computer without having to create an entire system from scratch.

To do this, we've split the problem into two parts with an interface in-between:

The long-term strategy is to:

In the short term, we've created several programs based on the JMRI libraries to move the project along and demonstrate its capabilities. (Why so many programs?...)

The most popular is DecoderPro, a tool for programming decoders. It simplifies the job of configuring complicated DCC decoders by providing screens on which you can select the various options and values you want. These screens show the exact contents of each specific decoder type. Both the programming screens and decoder information are stored in text files, so you can make up new ones as desired.

How can you change how JMRI does things?

There are several different ways to modify JMRI:
  1. You can use the JMRI interfaces to write programs for your own layouts. Making this easy is an important goal. This can be done via our scripting language.
  2. You can add new Java code to the program or modify the existing code. Fixing things that annoy you (aka bugs) is an easy place to jump in and contribute.
  3. You can write new general-purpose tools. Although this is a little harder than writing automation for your own layout, writing tools that other people use can be very satisfying.
  4. You can implement the JMRI interfaces for a new system. Having JMRI work with other systems is an important goal. Once an implementation for another system works, the general tools (e.g. symbolic programmer, automations tools, signaling, etc) can be immediately used.

JMRI project information (For people interested in how the software is being written)

Much of the discussion about JMRI development takes place on the JMRI-Developers mailing list: Subscribe, Archive

The Developer Wiki is where we are trying to document the structure of the code and how it's evolving. (This is an experimental effort, not yet really working, but we keep trying...)

SourceForge.net provides project hosting:

Code

All of the JMRI code is available from Subversion. See the "Getting the code via Subversion" and "SVN FAQ" pages for more information on how to do that.

If you just want to look at the contents of a few files, you can browse the Subversion repository over the web.

Building Your Own Copy

In addition to getting a copy of the JMRI source code and reading it, you can also compile your own version of the program to run. You can even include your own modifications if you'd like.

There several different ways to do this. If you're already familiar with one of the popular "Integrated Development Environments" (IDEs), look at the navigation bar to the left for instructions on how to build JMRI using NetBeans, XCode, Eclipse or JBuilder.

NetBeans provides a very convenient system for building, running, and if need be debugging the program. If you're not familiar with some other method, we recommend trying NetBeans first.

Alternately, if you'd like to edit code with your favorite text editor and compile it from a command line, please see the page of instructions for building with Ant.

Contributing

We encourage contributions of code, decoder definitions, improvements to web pages, etc, to the JMRI project so that we can distribute them to the rest of the community.

For your first small contributions, e.g. a new decoder file or small bug fix, please fill out a new "Patches" entry on SourceForge using our patches page (click new on the middle-left, then fill out the resulting form). You can attach the entire file there. If it's multiple files, and you're using an IDE like NetBeans, it's very easy to create a "diff patch file" to carry your changes, and that will save us a significant amount of work merging them in. Please see the instructions for creating a patch file with NetBeans.

It saves us a lot of work if, before you create and send the patch file, you make sure that your copy of the code is up to date, and that the unit tests all work.

If you are doing a significant amount of development, please contact us so the we can make it possible to directly commit your changes into our Subversion repository.

When you contribute your code to JMRI for the first time, we'll ask you to sign an assignment form that allows us to register copyright on the code, and gives us unlimited-duration license to redistribute it consistent with the JMRI licensing. (We regret this paperwork, but Matt Katzer's misuse of copyright makes it necessary). If other people also helped with the contribution, please let us know so we can add them to the acknowledgements page.

Licensing

We encourage people to build their own projects on top of JMRI. That's the original reason that the project was started!

JMRI is licensed only under the "GNU General Public License", sometimes called the "GPL". We use version 2 of the license, along with the "classpath exception" allowing people to link JMRI with their own code under more relaxed conditions. Copies of the license are distributed with the source and executable downloads, and can be gotten from the web.

This is both an "open source" and a "free" license. For more information on those definitions, please see the Open Source Initiative web pages, including their description of what Open Source means, and the Free Software Foundation web pages, particularly their licensing page.

Informally, the license means that there are only a few limitations on what you can do with JMRI. (Check the exact wording in the license for the details behind the following summary):

If you have any questions about this, please contact us directly.

Developer Code Swarm

We have created a Code Swarm of JMRI development from its inception to January 2009. A Code Swarm is a fascinating and dynamic visual representation of change as developers come and go and make changes to the files that make up a project. More information is available on the Code Swarm page.