JMRI: Technical InfoYou 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:
- "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
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:
- JMRI project page and project statistics.
- Trackers for Bugs, Feature Requests, and Patches.
- SourceForge-hosted Subversion Repository which you can browse through.
CodeAll 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 CopyIn 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.
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.
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.
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.