JMRI: Technical Information

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 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:

"Above" the interface are the cool tools that people want. We provide programmers for DCC decoders, layout controls, automation tools, etc. People are continuously contributing better and better tools that still will work on lots of type of computers, with lots of types of layouts.
"Below" the interface lies code that connects to specific layout hardware. We connected to a full range of systems: C/MRI, Digitrax, EasyDCC, Lenz, NCE, etc. We are certainly interested in connecting to other systems.

The long-term strategy is to:

Create a set of publicly available common interfaces for model railroad control code, suitable for use with any type of layout, from any type of computer.
Make these useful by providing quality implementations for as many types of layouts as possible.
Encourage interoperability of layout hardware and software through the use of common interfaces.

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:

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.
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.
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.
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

GitHub provides our software repositories via the GitHub JMRI organization.

SourceForge.net provides project support:

JMRI project page and project statistics (for that information tracked by SourceForge).

Code

All of the JMRI code is available from GitHub. See the "Getting the code via Git" and "Git 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 program source code and web site source code 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 are 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, Eclipse, or IntelliJ.

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 initial and/or small contributions, e.g. a new decoder file or small bug fix, you can fill out a new "issue" on GitHub. You can attach the entire file there. If it's more than one 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're contributing multiple changes, or working on a larger project, JMRI has tools and procedures that make it easy and reliable to connect your work to the rest of the JMRI community. Basically, you work in a local copy of the JMRI code repository, and you're changes can be "pulled" in when you're ready to contribute them. See our page on "Being A JMRI Developer" for instructions on how to more effectively contribute code changes.

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 JMRI® 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):

You can redistribute it, for free or for a charge to cover your costs.
You can build additional programs on top of all or part of JMRI, and distribute JMRI with them. This is OK whether or not you charge for your program.
You can modify the JMRI code for your own purposes.
You can distribute that modified code, though in that case you either have to make your modifications available to us, or also distribute an unmodified version at the same time.
You cannot use part or all of JMRI in another project without either giving credit to JMRI, or making special arrangements with us.
This includes decoder definition files: You are welcome to use them, including reformatting their content to another form, but you must give JMRI credit for their content.

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

Visualizations of JMRI Development Activity

You can see a summary of the JMRI developer activity on the GitHub project page for the main code repository and the website.

The JMRI CodeFlower provides a dynamic view of the whole GitHub repository. It shows the relative size of the code in each file and the structure in which the files are stored.

More detailed metrics are available on the JMRI OpenHub pages on contributors and commits.

Dennis Miller created a Code Swarm of JMRI development that represents activity from 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.