Serge NOEL
227 lines
10 KiB
Plaintext
227 lines
10 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: Getting the Code</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="keywords" content="JMRI technical code Git download">
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI Code: Getting the Code</h1>
|
|
|
|
<h2>Background</h2>
|
|
|
|
<p>"<a href="https://git-scm.com">Git</a>" 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 <a href="https://github.com/JMRI">GitHub.com</a>. The <a href="WebSite.shtml">JMRI web
|
|
site</a> is in a similar repository.</p>
|
|
|
|
<h2 id="view">Viewing the Code Online</h2>
|
|
|
|
<p>You can <a href="https://github.com/JMRI/JMRI">browse the JMRI code directly</a> on that
|
|
site. For example, if you'd like to look at this page, <a href=
|
|
"https://github.com/JMRI/JMRI/blob/master/help/en/html/doc/Technical/getgitcode.shtml">click
|
|
this link</a> to display its source HTML code.</p>
|
|
|
|
<h3 id="propose">Proposing Changes Online</h3>
|
|
|
|
<p>If you want to suggest a change to a file, for example a web page like this one, first get
|
|
a free <a href="https://github.com/join">GitHub account</a> and sign in.</p>
|
|
|
|
<p><a href="images/GitHubPencil.png"><img src="images/GitHubPencil.png"
|
|
class="floatRight" alt="GitHub screen shot"></a>Then go to the file you want to change and click the pencil icon on the upper-right of the
|
|
page.</p>
|
|
|
|
<a href="images/GitHubProposeFileChange.png"><img src="images/GitHubProposeFileChange.png"
|
|
alt="GitHub screen shot"></a>
|
|
<p>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.</p>
|
|
|
|
<p>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.<br>
|
|
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 (<a href="gitdeveloper.shtml#pull">more
|
|
details</a>).</p>
|
|
|
|
<h2 id="get">Get Your Own Copy</h2>
|
|
|
|
<p>Our source code is distributed using <a href="https://git-scm.com">Git</a>. (We also keep
|
|
the <a href="WebSite.shtml">website</a> 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 <a href="WebSite.shtml">web
|
|
site</a>, 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.</p>
|
|
|
|
<p>Although there are lots of ways to use Git, the next sections show the most common
|
|
ones:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="#desktop">Using the GitHub Desktop application</a> (Mac or Windows only)
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#cmd">Using the command line</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ide">Using an Integrated Development Environment (IDE)</a>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If you want to develop changes to the code, see the "<a href=
|
|
"gitdeveloper.shtml">Developing with JMRI Code</a>" page.</p>
|
|
|
|
<p>Also check the <a href="GitFAQ.shtml">JMRI Git FAQ page</a>.</p>
|
|
|
|
<h3 id="desktop">Using the GitHub Desktop Application</h3>
|
|
|
|
<p>The <a href="https://desktop.github.com">GitHub Desktop</a> 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.</p>
|
|
|
|
<ul>
|
|
<li>There's a download link on the <a href="https://desktop.github.com">GitHub Desktop
|
|
application web page</a>. Get the download and install it using the instructions there.
|
|
</li>
|
|
|
|
<li>Open the GitHub Desktop application.</li>
|
|
|
|
<li>In your web browser, go to the GitHub site for the "<a href=
|
|
"https://github.com/JMRI/JMRI">JMRI repository</a>" (clicking the link should take you
|
|
there).
|
|
</li>
|
|
|
|
<li>Click the "Clone in Desktop" button on the top right.<br>
|
|
<a href="images/GitHubCloneDeskop.png"><img src="images/GitHubCloneDeskop.png" alt=
|
|
"Clone to desktop button in GitHub web"></a>
|
|
</li>
|
|
|
|
<li>The GitHub Desktop application will show a dialog where you can select the download
|
|
location. Change that if desired:<br>
|
|
<a href="images/GhDtCloneDialog.png"><img src="images/GhDtCloneDialog.png" alt=
|
|
"Clone dialog in GitHub Desktop Mac"></a><br>
|
|
and click "Clone".
|
|
</li>
|
|
|
|
<li>The download will start. It's likely to take a couple minutes.</li>
|
|
|
|
<li>For more details, please see the our <a href="githubdesktopintro.shtml">page on using
|
|
GitHub Desktop</a> and the <a href="GitFAQ.shtml">Git FAQ help page</a>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>After the download is complete, there are menu items under the application "Repository"
|
|
menu to access the code directory:<br>
|
|
<a href="images/GitDtRepoSettingsMenu.png"><img src="images/GitDtRepoSettingsMenu.png" alt=
|
|
"Repository menu in GitHub Desktop"></a><br>
|
|
You can also navigate there directly using your file system.</p>
|
|
|
|
<p>Inside, you'll find directories called <code>xml</code>, <code>resources</code>,
|
|
<code>jython</code>, <code>help</code>, <code>lib</code>, <code>java</code> and others.</p>
|
|
|
|
<p>In the <code>java</code> directory, you will find a <code>src</code> directory that
|
|
contains the source code for JMRI itself, and a <code>tests</code> directory that contains
|
|
various test routines.</p>
|
|
|
|
<p>You can look at the code with your favorite text editor.<br>
|
|
To compile and run the code, you need one of the compilation tools described on the bar at
|
|
the left: <a href="Ant.shtml">Ant</a>, <a href="Eclipse.shtml">Eclipse</a>, <a href=
|
|
"NetBeans.shtml">NetBeans</a>, <a href="IntelliJ.shtml">IntelliJ</a>, etc. (Ant may be the
|
|
easiest to install and use, and is the primary example in the documentation)</p>
|
|
|
|
<p>For more information on using the GitHub Desktop application, please see the our <a href=
|
|
"githubdesktopintro.shtml">page on using GitHub Desktop</a> and the <a href=
|
|
"GitFAQ.shtml">Git FAQ help page</a>.</p>
|
|
|
|
<h3 id="cmd">Using the command line</h3>
|
|
|
|
<p>First, check whether Git is installed on your computer. From a command line, do<br>
|
|
<code>git --version</code> (note the two hyphens).<br>
|
|
If it replies with a version greater than 2, e.g. 2.3.8, you're all set. If not, there are
|
|
<a href="GitFAQ.shtml#install">instructions for installing Git</a> in the <a href=
|
|
"GitFAQ.shtml">Git FAQ</a>. Install Git, then come back here.</p>
|
|
|
|
<p>To get a local copy of the code, you tell Git to "clone" it from our repository. The
|
|
command to do that is:</p>
|
|
|
|
<pre>
|
|
<code>
|
|
$ git clone https://github.com/JMRI/JMRI.git
|
|
</code>
|
|
</pre>
|
|
This will create a new "JMRI" directory and download the code into it.
|
|
<p>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:</p>
|
|
|
|
<pre>
|
|
<code>
|
|
$ git pull https://github.com/JMRI/JMRI.git
|
|
</code>
|
|
</pre>
|
|
<p>After the checkout is complete, go to the new JMRI directory that was created. Inside,
|
|
you'll find directories called <code>xml</code>, <code>resources</code>, <code>jython</code>,
|
|
<code>help</code>, <code>lib</code>, <code>java</code> and others.</p>
|
|
|
|
<p>In the <code>java</code> directory, you will find a <code>src</code> directory that
|
|
contains the source code for JMRI itself, and a <code>tests</code> directory that contains
|
|
various test routines.</p>
|
|
|
|
<p>You can look at the code with your favorite text editor.</p>
|
|
|
|
<p>To compile and run the code, you need one of the compilation tools described on the bar at
|
|
the left: <a href="Ant.shtml">Ant</a>, <a href="Eclipse.shtml">Eclipse</a>, <a href=
|
|
"NetBeans.shtml">NetBeans</a>, <a href="IntelliJ.shtml">IntelliJ</a> etc. (Ant may be the
|
|
easiest to install and use, and is the primary example in the documentation)</p>
|
|
|
|
<h3 id="ide">Using an Integrated Development Environment (IDE)</h3>
|
|
|
|
<p>Most IDEs have Git support build in. For the ones that can build JMRI, we have specific
|
|
instructions:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="Ant.shtml">Ant</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="Eclipse.shtml">Eclipse</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="NetBeans.shtml">NetBeans</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="IntelliJ.shtml">IntelliJ</a>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2>Access to Old Releases</h2>
|
|
|
|
<p>The best way to retrieve the source for releases 4.1.2 and earlier is from the <a href=
|
|
"getsvncode.shtml">SVN Repository</a> (see the link for details.</p>
|
|
|
|
<p>The best way to retrieve the source for releases 2.12 and earlier is from the <a href=
|
|
"getcvscode.shtml">CVS Repository</a> (see the link for details.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|