Software documentation

Development tools

Code Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI: Getting the Code

Background

"Git" is a powerful, free system for managing code as it's worked-on by a distributed group. Like SVN before it, and CVS before that, it allows a group like JMRI to cooperate effectively. We keep the JMRI code, help files, sample scripts, XML files, etc. in a Git repository hosted on GitHub.com. The JMRI web site is in a similar repository.

Viewing the Code Online

You can browse the JMRI code directly on that site. For example, if you'd like to look at this page, click this link to display its source HTML code.

Proposing Changes Online

GitHub screen shot

If you want to suggest a change to a file, for example a web page like this one, first get a free GitHub account and sign in.

Then go to the file you want to change and click the pencil icon on the upper-right of the page.

GitHub screen shot This will, after a second or two, give you a page where you can edit the contents of the file with your suggested change. Don't worry, you're not actually changing JMRI's original code, just your personal copy of the code.

Then fill out the form at the bottom with a useful subject line, and a description of why this is a good change, and click the "Propose file change" button. This saves your edits to your personal copy on the Git server.
Next, click on the "Pull request" button at the top right of the code panel. This sends your change to the people who've agreed to maintain the JMRI central code, who will review and (usually) include it in the next JMRI release (more details).

Get Your Own Copy

Our source code is distributed using Git. (We also keep the web site in Git, if you'd like to work with the source for that directly.) If you want to work with the JMRI code, the full web site, or any other large part of JMRI, spending a couple minutes getting Git set up is well worth it. We're sorry, but we just can't support other methods (sending around individual files, etc.), as they're just too error prone.

Although there are lots of ways to use Git, the next sections show the most common ones:

If you want to develop changes to the code, see the "Developing with JMRI Code" page.

Also check the JMRI Git FAQ page.

Using the GitHub Desktop Application

The GitHub Desktop application is a very convenient tool for working with Git repositories. Unfortunately, it's only available for Mac and Windows. For Linux, please use one of the other methods.

After the download is complete, there are menu items under the application "Repository" menu to access the code directory:
Repository menu in GitHub Desktop
You can also navigate there directly using your file system.

Inside, you'll find directories called xml, resources, jython, help, lib, java and others.

In the java directory, you will find a src directory that contains the source code for JMRI itself, and a tests directory that contains various test routines.

You can look at the code with your favorite text editor.
To compile and run the code, you need one of the compilation tools described on the bar at the left: Ant, Eclipse, NetBeans, IntelliJ, etc. (Ant may be the easiest to install and use, and is the primary example in the documentation)

Using the command line

First, check whether Git is installed on your computer. From a command line, do
git --version (note the two hyphens).
If it replies with a version greater than 2, e.g. 2.3.8, you're all set. If not, there are instructions for installing Git in the Git FAQ. Install Git, then come back here.

To get a local copy of the code, you tell Git to "clone" it from our repository. The command to do that is:


  $ git clone https://github.com/JMRI/JMRI.git
  
This will create a new "JMRI" directory and download the code into it.

If you have already gotten a copy of the code on your computer and want to update it to the most recent contents of the main JMRI repository, start in the JMRI code directory and to:


  $ git pull https://github.com/JMRI/JMRI.git
  

After the checkout is complete, go to the new JMRI directory that was created. Inside, you'll find directories called xml, resources, jython, help, lib, java and others.

In the java directory, you will find a src directory that contains the source code for JMRI itself, and a tests directory that contains various test routines.

You can look at the code with your favorite text editor.

To compile and run the code, you need one of the compilation tools described on the bar at the left: Ant, Eclipse, NetBeans, IntelliJ etc. (Ant may be the easiest to install and use, and is the primary example in the documentation)

Using an Integrated Development Environment (IDE)

Most IDEs have Git support build in. For the ones that can build JMRI, we have specific instructions:

Access to Old Releases

The best way to retrieve the source for releases 4.1.2 and earlier is from the SVN Repository. Please see those instructions for details.

The best way to retrieve the source for releases 2.12 and earlier is from the CVS Repository. Please see those instructions for details.