/
getgitcode.shtml
263 lines (212 loc) · 10.4 KB
/
getgitcode.shtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">
<title>JMRI: Getting the Code</title>
<meta name="author" content="Bob Jacobsen">
<meta name="keywords" content="JMRI technical code Git download">
<!-- The combination of "Define" and {Header,Style, Logo and Footer} comments -->
<!-- are an arbitrary design pattern used by the update.pl script to -->
<!-- easily replace the common header/footer code for all the web pages -->
<!-- delete the following 2 Defines if you want to use the default JMRI logo -->
<!-- or change them to reflect your alternative logo -->
<!--#include virtual="/Style.shtml" -->
</head><!--#include virtual="/Header.shtml" -->
<body>
<div id="mBody">
<!--#include virtual="Sidebar" -->
<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>
<a name="view" id="view"></a>
<h2>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><a name="propose" id="propose"></a>
<h3>Proposing Changes Online</h3><a href=
"images/GitHubPencil.png"><img src="images/GitHubPencil.png"
align="right" height="50" width="142" alt=
"GitHub screen shot"></a>
<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>Then go to the file you want to change and click the
pencil icon on the upper-right of the page.</p>
<p><a href="images/GitHubProposeFileChange.png"><img src=
"images/GitHubProposeFileChange.png" align="right" height=
"135" width="221" alt="GitHub screen shot"></a> 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><a name="get"
id="get"></a>
<h2>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">web site</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><a name="desktop" id="desktop"></a>
<h3>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" height="315" width=
"409"></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" height="184" width=
"267"></a><br>
and click "Clone".</li>
<li>The download will start. It's likely to take a couple
minutes.</li>
<li>For more details, see the our <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" height="175" width=
"275"></a>
<br>You can also navigate there directly using your file
system.</p>
<p>Inside, you'll find directories called <tt>xml</tt>,
<tt>resources</tt>, <tt>jython</tt>, <tt>help</tt>,
<tt>lib</tt>, <tt>java</tt> and others.</p>
<p>In the <tt>java</tt> directory, you will find a
<tt>src</tt> directory that contains the source code for JMRI
itself, and a <tt>tests</tt> 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><a name="cmd" id="cmd"></a>
<h3>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 <tt>xml</tt>, <tt>resources</tt>, <tt>jython</tt>,
<tt>help</tt>, <tt>lib</tt>, <tt>java</tt> and others.</p>
<p>In the <tt>java</tt> directory, you will find a
<tt>src</tt> directory that contains the source code for JMRI
itself, and a <tt>tests</tt> 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><a name="ide" id="ide"></a>
<h3>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="/Footer.shtml" -->
</div><!-- closes #mainContent-->
</div><!-- closes #mBody-->
</body>
</html>