JMRI: Getting the Code
Author: Bob Jacobsen
Keywords: JMRI technical code Git download

# JMRI Code: Getting the Code

## Background

"Git" is a powerful, free system for managing code as it's worked-on by a distributed group. 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

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.

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

- Using the GitHub Desktop application (Mac or Windows only)
- Using the command line
- Using an Integrated Development Environment (IDE)

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.

- There's a download link on the GitHub Desktop application web page. Get the download and install it using the instructions there.
- Open the GitHub Desktop application.
- In your web browser, go to the GitHub site for the "JMRI repository" (clicking the link should take you there).
- Click the "Clone in Desktop" button on the top right.
- The GitHub Desktop application will show a dialog where you can select the download location. Change that if desired:
  and click "Clone".
- The download will start. It's likely to take a couple minutes.
- For more details, please see the our page on using GitHub Desktop and the Git FAQ help page.

After the download is complete, there are menu items under the application "Repository" menu to access the code directory:
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)

For more information on using the GitHub Desktop application, please see the our page on using GitHub Desktop and the Git FAQ help page.

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

- Ant
- Eclipse
- NetBeans
- IntelliJ

## Access to Old Releases

The best way to retrieve the source for releases 4.1.2 and earlier is from the SVN Repository (see the link for details.

The best way to retrieve the source for releases 2.12 and earlier is from the CVS Repository (see the link for details.