Serge NOEL
734 lines
29 KiB
Plaintext
734 lines
29 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: Building with Apache NetBeans</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="author" content="B. Milhaupt">
|
|
<meta name="keywords" content="JMRI technical code Apache NetBeans">
|
|
<!--#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">
|
|
<!-- this was created by running the command `asciidoctorj -a toc NetBeans.adoc`
|
|
and copying the contents of body element in the resultant NetBeans.html file -->
|
|
<h1>JMRI Code: Building with Apache NetBeans</h1>
|
|
|
|
<div id="toc">
|
|
<h2>
|
|
Table of Contents
|
|
</h2>
|
|
|
|
<ul>
|
|
<li>
|
|
<a href="#introduction">Introduction</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#installation">Installation</a>
|
|
<ul>
|
|
<li>
|
|
<a href="#linux">Linux</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#macos">macOS</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#windows">Windows</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#using_apache_netbeans_with_jmris_git_code_repository">Using Apache NetBeans
|
|
with JMRI’s Git Code Repository</a>
|
|
<ul>
|
|
<li>
|
|
<a href="#checking_out_code">Checking out code</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#local_commits">Local Commits</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#updating_the_code_from_git">Updating the code from Git</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#creating_a_pull_request">Creating a Pull Request</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#building_and_running_jmri">Building and running JMRI</a>
|
|
<ul>
|
|
<li>
|
|
<a href="#prime">Prime</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#build">Build</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#run_an_application">Run an Application</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#debug_an_application">Debug an Application</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#profile_an_application">Profile an Application</a>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#making_a_jar_file">Making a Jar File</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#making_a_release_package_for_windows_using_nsis">Making a release package for
|
|
Windows using NSIS</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#using_apache_netbeans_xml_tools">Using Apache NetBeans XML tools</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#running_spotbugs">Running SpotBugs</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#loading_a_specific_branch_from_github">Loading a Specific Branch from
|
|
GitHub</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#NetBeansGuiForms">Using NetBeans "GUI-building" tools</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<h2 id="introduction">Introduction</h2>
|
|
|
|
<p><a href="https://netbeans.apache.org">Apache NetBeans</a> makes a great platform
|
|
for working with JMRI. The JMRI code is set up to work with Apache NetBeans with
|
|
almost no additional setup.</p>
|
|
|
|
<p>Apache NetBeans is a very powerful Integrated Development Environment (IDE), which
|
|
can make working with the JMRI code pretty easy. But it takes a little getting used
|
|
to, and reading the <a href="https://netbeans.apache.org/help/">tutorials</a> will be
|
|
helpful.</p>
|
|
|
|
<h2 id="installation">Installation</h2>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Download and install a Java 11 or newer <a href="https://adoptium.net/">Java
|
|
Development Kit (JDK)</a> (It is recommended to use a package manager if possible
|
|
to ensure security updates can be automatically installed)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Download Apache NetBeans from <a href=
|
|
"https://netbeans.apache.org/download/">netbeans.apache.org</a> (It is recommended
|
|
to use a package manager if possible to ensure security updates can be
|
|
automatically installed)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Run the Apache NetBeans installer</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3 id="linux">Linux</h3>
|
|
|
|
<p>Apache NetBeans can also be installed as a <a href=
|
|
"https://snapcraft.io/netbeans">snap package</a> for Linux.</p>
|
|
|
|
<h3 id="macos">macOS</h3>
|
|
|
|
<p>Apache NetBeans and the OpenJDK 11 JDK can be installed using <a href=
|
|
"https://brew.sh">Homebrew</a> from the terminal:</p>
|
|
|
|
<code>brew install --cask openjdk@11 netbeans</code>
|
|
|
|
<h3 id="windows">Windows</h3>
|
|
|
|
<p>Note:<br>
|
|
Due to different handling of Line Endings characters (<code>LF / CR
|
|
LF</code>) between Windows and other systems - namely Unix and OS X (see
|
|
<a href="GitFAQ.shtml#lineends">Handling Line Ends</a>) - it is of the
|
|
utmost importance that all Windows users adopt the following settings for
|
|
their development environment. This is absolutely required so that Git can
|
|
track individual changes on files that you commit.</p>
|
|
|
|
<p>If you are using <a href="githubdesktopintro.shtml">GitHub Desktop</a>
|
|
to manage your copy of the JMRI code, create Pull Requests etc. then this will
|
|
take care of properly convert line endings to the correct format.
|
|
There is no need to change anything within NetBeans.</p>
|
|
|
|
<p>If instead, you use NetBeans to directly manage your Repository and
|
|
don’t follow these instructions, you’ll mess up the line endings
|
|
in the files you commit, which will in turn make their revision history
|
|
much harder to access. Files in this condition will not be accepted as pull
|
|
requests.</p>
|
|
|
|
<p>As a first step, as JMRI has adopted <code>LF</code> as a convention for
|
|
Line Endings, it is required to set the <code>core.autocrlf</code> setting
|
|
to <code>true</code> (see <a href=
|
|
"https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings">"Dealing with
|
|
line endings" on GitHub Help)</a></p>
|
|
|
|
<p class="important">You <strong>must</strong> install and configure the <a href=
|
|
"https://plugins.netbeans.apache.org/catalogue/?id=31">"Change
|
|
Line Endings on Save" plugin</a> as follows before using Git via Apache NetBeans.</p>
|
|
|
|
<h4 id="change_line_endings_on_save_plugin"><em>Change Line Endings on Save</em>
|
|
Plugin</h4>
|
|
|
|
<h5 id="installation_2">Plugin Installation</h5>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Choose <strong class="menu">Tools</strong> <strong class="caret">›</strong>
|
|
<strong class="menuitem">Plugins</strong></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Settings</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Select <em>Netbeans Plugin Portal</em> and ensure it is active</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Available Plugins</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Select <em>Change Line Endings on Save</em></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Install</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Follow the prompts to complete installation</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Restart Apache NetBeans when prompted</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h4 id="configuration">Plugin Configuration</h4>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Choose <span class="menuseq"><strong class=
|
|
"menu">Tools</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Options</strong></span></p>
|
|
<p><a href="images/NetbeansChangeLineEndingsPluginConfiguration.png"><img src=
|
|
"images/NetbeansChangeLineEndingsPluginConfiguration.png" alt=
|
|
"Configuration Window"></a>
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Editor</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click the <span class="textbutton">Line Endings</span> tab</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Select <em>Enable adjusting the line endings</em></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Choose <em>Unix (LF)</em> from the popup menu</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>To be prompted before line endings are adjusted, select <em>Show
|
|
confirmation dialog before adjusting the line endings</em></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">OK</span>. </p></li>
|
|
</ol>
|
|
|
|
<p>You can check that the plug-in is properly installed by going to go to <code>Tools
|
|
> Plugins > Installed</code>, where you should see the ChangeLineEndingsPlugin in the list.</p>
|
|
|
|
<h2 id="using_apache_netbeans_with_jmris_git_code_repository">Using Apache NetBeans with
|
|
JMRI’s Git Code Repository</h2>
|
|
|
|
<p>GitHub provides JMRI’s code repository using the Git tool. For more information on
|
|
how JMRI uses Git, see the JMRI Help on <a href="getgitcode.shtml">Getting the code
|
|
via Git</a> and <a href="GitFAQ.shtml">Git FAQ</a>.</p>
|
|
|
|
<p>Once set up, Apache NetBeans provides built-in support for using Git.</p>
|
|
|
|
<p>For more information on Git and Apache NetBeans, see the <a href=
|
|
"https://netbeans.apache.org/kb/docs/ide/git.html">NetBeans Git help page</a></p>
|
|
|
|
<h3 id="checking_out_code">Checking out code</h3>
|
|
|
|
<p>In Apache NetBeans, under the "Team" menu, select Git, then Clone Repository.
|
|
Enter the <a href="https://github.com/JMRI/JMRI.git" class=
|
|
"bare">https://github.com/JMRI/JMRI.git</a> repository URL from the <a href=
|
|
"https://github.com/JMRI/JMRI">JMRI GitHub page</a> on the Apache NetBeans form
|
|
under "Repository URL". We recommend that you also enter your GitHub user name and
|
|
password on the form, so we can attribute your contributions to you later. Click
|
|
"Next". Make sure that the "master*" box is checked to pull down the main version
|
|
of the code. Click "Next", and then click "Finish".</p>
|
|
|
|
<p>It’ll take a long time to pull down a copy of the code (note the progress bar in
|
|
the lower right), but then you’re good to go.</p>
|
|
|
|
<h3 id="local_commits">Local Commits</h3>
|
|
|
|
<p>When using Git, the "commit" operation is local to your computer. It doesn’t
|
|
make any changes to the main JMRI repository.</p>
|
|
|
|
<p>You’re encouraged to commit often, so that your changes are safely stored away
|
|
from your working directory. Having each small change separately recorded can be
|
|
incredibly helpful later on if you have to track down where a problem was
|
|
introduced.</p>
|
|
|
|
<h3 id="updating_the_code_from_git">Updating the code from Git</h3>
|
|
|
|
<p>From time to time, you should update your local copy of the code to match the
|
|
current "HEAD" of the main JMRI Git repository contents. The basic process is to
|
|
pull the most recent copies from the main JMRI repository, doing any merging that’s
|
|
needed if you’ve made conflicting changes, and then pushing that up to your own
|
|
GitHub repository.</p>
|
|
|
|
<p>To do this, use the Apache NetBeans [Team] → [Remote] → [Pull from Upstream]
|
|
menu choice. Tell Apache NetBeans to pull from the "github" remote you defined
|
|
above.</p>
|
|
|
|
<p>You may also update a single file or the contents of a folder, by right-clicking
|
|
on an item in the "Files" window, then selecting [Git] → [Remote] → [Pull from
|
|
Upstream].</p>
|
|
|
|
<h3 id="creating_a_pull_request">Creating a Pull Request</h3>
|
|
|
|
<p>A "Pull Request" (PR) is an easy way to gather all your changes, even if they
|
|
span multiple files, into something that you can then submit for inclusion in the
|
|
main JMRI repository.</p>
|
|
|
|
<p>First, you need to set up a GitHub account and your own repository.</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Get a <a href="https://github.com/join">GitHub account</a> and login</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Tell GitHub to <a href=
|
|
"https://docs.github.com/en/get-started/quickstart/fork-a-repo">"fork" JMRI’s repository</a>
|
|
into one of your own. There’s a <a href=
|
|
"https://docs.github.com/en/get-started/quickstart/fork-a-repo">good help page</a>, but
|
|
basically you go to the <a href="https://github.com/JMRI/JMRI">JMRI repository
|
|
page</a> and click the "fork" button in the upper right.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>This gives you your own repository, which you can then work with freely.</p>
|
|
|
|
<p>Next, push the changes up to your repository. (Anybody can push to their own
|
|
repository, but most people don’t have permission to directly modify the main JMRI
|
|
repository; that’s why the pull request is needed) To do this:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Use the Apache NetBeans [Team] > [Remote] > [Push...] menu choice. (If
|
|
you try to use the "Push to Upstream" choice, it will try to write back to the
|
|
main repository, and will fail.)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click on Specify Git Repository, and enter the URL for your own repository,
|
|
e.g.<br>
|
|
<span class="wide" style="font-family: monospace;">https://github.com/<yourname>/JMRI.git</span>
|
|
</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Then click next.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Apache NetBeans will check with the repository, and show an indication of
|
|
branches to push e.g. "master → master" Check the appropriate box to for the
|
|
branch you’ve been working on.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click Next and Finish. Netbeans will do the actual push to your
|
|
repository.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>You can repeat this as many times as you’d like as you’re working on your
|
|
changes. Each time, the most recent changes are pushed up and made available.</p>
|
|
|
|
<p>Finally, when your change is ready to submit, go to the GitHub website to
|
|
<a href="gitdeveloper.shtml#pull">fill out and submit a pull request</a>.</p>
|
|
|
|
<p>Eventually, somebody will look at the pull request and decide whether to merge
|
|
it in. Sometimes they’ll ask for additional changes. In that case, you can update
|
|
the pull request by just pushing new changes to your repository, where they’ll
|
|
automatically be picked up.</p>
|
|
|
|
<h2 id="building_and_running_jmri">Building and running JMRI</h2>
|
|
|
|
<p>Tip:<br>
|
|
Ensure your computer is connected to the internet the first
|
|
time you build, test, or run JMRI after checking out a new copy of JMRI from
|
|
GitHub to allow any potentially missing external dependencies or build tools to
|
|
be automatically downloaded.</p>
|
|
|
|
<h3 id="prime">Prime</h3>
|
|
|
|
<p><a href="images/netbeans-project-warning.png"><span class=
|
|
"image related right"><img src="images/netbeans-project-warning.png" alt=
|
|
"Project warnings"></span></a> The first time you open the JMRI project
|
|
in Apache NetBeans, a warning icon will be shown on the project. This warning
|
|
indicates Apache NetBeans has a problem with the project. Usually the first time
|
|
warning indicates that build artifacts are missing.</p>
|
|
|
|
<p>To resolve this problem:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Select the JMRI project</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Choose <span class="menuseq"><strong class="menu">shortcut
|
|
menu</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Resolve Project Problems…</strong></span> (the shortcut menu is
|
|
usually opened by right-clicking on the project) <a href=
|
|
"images/netbeans-resolve-project-problems-menu.png">Show example...</a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p><a href="images/netbeans-resolve-project-problems.png"><span class=
|
|
"image related right"><img src="images/netbeans-resolve-project-problems.png"
|
|
alt="Resolve Project Problems dialog"></span></a></p>
|
|
Click <span class="textbutton">Resolve...</span>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Close</span> once the warning icon changes to
|
|
an OK icon</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3 id="build">Build</h3>
|
|
|
|
<p>To build JMRI, choose <span class="menuseq"><strong class=
|
|
"menu">Run</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Build Project (JMRI)</strong></span> or <span class=
|
|
"menuseq"><strong class="menu">Run</strong> <strong class="caret">›</strong>
|
|
<strong class="menuitem">Clean and Build Project (JMRI)</strong></span>.</p>
|
|
|
|
<p>Tip:<br>
|
|
To build only the JMRI Java source code, run the maven lifecycle phase <code>compile</code>.</p>
|
|
|
|
<h3 id="run_an_application">Run an Application</h3>
|
|
|
|
<p><a href="images/netbeans-run-project.png"><span class=
|
|
"image related right"><img src="images/netbeans-run-project.png" alt=
|
|
"Select Main Class for Execution dialog"></span></a> To run a JMRI
|
|
application, choose <span class="menuseq"><strong class=
|
|
"menu">Run</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Run Project (JMRI)</strong></span> or click the Run icon in the tool
|
|
bar. You will be prompted for the JMRI main class to run the first time you run the
|
|
project.</p>
|
|
|
|
<p>The JMRI applications are launched from the main classes:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<td class="hdlist1">DecoderPro</td>
|
|
<td class="hdlist2">
|
|
<p><code>apps.DecoderPro.DecoderPro</code>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="hdlist1">PanelPro</td>
|
|
<td class="hdlist2">
|
|
<p><code>apps.PanelPro.PanelPro</code>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td class="hdlist1">SoundPro</td>
|
|
<td class="hdlist2">
|
|
<p><code>apps.SoundPro.SoundPro</code>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
Tip:<br>
|
|
A new JMRI checkout should build cleanly. If not, please share your configuration on
|
|
<a href="https://jmri-developers.groups.io">jmri-developers groups.io</a> or on GitHub create an
|
|
<a href="https://github.com/JMRI/JMRI/issues">issue</a> applying for assistance.
|
|
</p>
|
|
|
|
<h3 id="debug_an_application">Debug an Application</h3>
|
|
|
|
<p>To debug a JMRI application, choose <span class="menuseq"><strong class=
|
|
"menu">Debug</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Debug Project (JMRI)</strong></span> or click the Debug icon in the tool
|
|
bar. You will be prompted for the JMRI main class to debug the first time you run
|
|
the project.</p>
|
|
|
|
<h3 id="profile_an_application">Profile an Application</h3>
|
|
|
|
<p>To profile a JMRI application, choose <span class="menuseq"><strong class=
|
|
"menu">Profile</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">Profile Project (JMRI)</strong></span> or click the Profile icon in the
|
|
tool bar. You will be prompted for the JMRI main class to profile the first time
|
|
you run the project.</p>
|
|
|
|
<h2 id="making_a_jar_file">Making a Jar File</h2>
|
|
|
|
<p>Most of the code in a normal JMRI installation lives in a file called jmri.jar. If
|
|
you want to replace this with your updated version, you need to create a new jmri.jar
|
|
file from your modified code.</p>
|
|
|
|
<p>To do this, ctrl-click (or right-click) on the name of the "JMRI" project in the
|
|
"Projects" window. This will open a pop-up menu, on which you’ll find "Make Jar
|
|
File". Select that, and a new jmri.jar file will be produced in the project’s main
|
|
directory.</p>
|
|
|
|
<p>Alternately, from the "Files" window, right-click on the build.xml file, and
|
|
select "Run Target", then "jar".</p>
|
|
|
|
<h2 id="making_a_release_package_for_windows_using_nsis">Making a release package for
|
|
Windows using NSIS</h2>
|
|
|
|
<p>It is possible for Apache NetBeans users to create a release package for use on
|
|
the Windows platform. This requires installation of the Nullsoft Scriptable Install
|
|
System (NSIS), which can be downloaded from <a href=
|
|
"https://sourceforge.net/projects/nsis/">the NSIS project website</a> on
|
|
SourceForge.</p>
|
|
|
|
<p>Comments in <a href="https://github.com/JMRI/JMRI/blob/master/scripts/WinInstallFiles/LaunchJMRI.nsi#L21"
|
|
>LaunchJMRI.nsi</a> suggest that it is also necessary to install ( extract ) the
|
|
"Large strings" build available from
|
|
<a href="https://nsis.sourceforge.io/Special_Builds">NSIS Special Builds<a>.
|
|
|
|
<p>Once NSIS is installed on the computer, it is necessary to create a file called
|
|
local.properties in the same directory as JMRI's build.xml file. This file is
|
|
specifically <em>not</em> checked in via GitHub, so that your machine-specific tool
|
|
installation paths are <em>not</em> checked in to GitHub. Create the file, and add a
|
|
variable definition with the correct path to the directory which includes the NSIS
|
|
executable, such as:</p>
|
|
|
|
<p>nsis.home=C:/Program Files (x86)/NSIS/</p>
|
|
|
|
<p>or</p>
|
|
|
|
<p>nsis.home=/opt/nsis/nsis-2.46/</p>
|
|
|
|
<p><em>Note:</em> Make sure the trailing / is present.</p>
|
|
|
|
<p>With the NSIS package installed to your computer, and build.xml properly modified,
|
|
the Windows package may be created by running the "package-windows" ant target in
|
|
build.xml.</p>
|
|
|
|
<h2 id="using_apache_netbeans_xml_tools">Using Apache NetBeans XML tools</h2>
|
|
|
|
<p>Apache NetBeans has nice tools for working with XML files, including editing and
|
|
validating them. JMRI uses XInclude to include XML fragments in other XML files via
|
|
URLs to <a href="https://www.jmri.org/xml">the JMRI website</a>. JMRI programs convert
|
|
these at run time to local file references; however Apache NetBeans must be
|
|
configured to do this if you want to edit JMRI XML files while offline.</p>
|
|
|
|
<p>To configure Apache NetBeans to allow offline XML editing:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Choose <span class="menuseq"><strong class=
|
|
"menu">Tools</strong> <strong class="caret">›</strong> <strong class=
|
|
"menuitem">DTDs and XML Schemas</strong></span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Add Catalog...</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Select the <em>Catalog Type</em> <code>OASIS Catalog Resolver</code></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Browse...</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Navigate to <code>/path-to-your-JMRI-project/xml/catalog.xml</code></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">OK</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">OK</span></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click <span class="textbutton">Close</span></p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Note:<br>
|
|
the XML catalog location is not project specific, so if you
|
|
are working on multiple JMRI projects, whichever project you add the catalog from
|
|
will be used, not the current project.</p>
|
|
|
|
<h2 id="running_spotbugs">Running SpotBugs</h2>
|
|
|
|
<p>The SpotBugs tool is a static code analysis tool which examines JAVA source code
|
|
for common coding issues.</p>
|
|
|
|
<p>To run the SpotBugs tool on JMRI code, execute the maven goal
|
|
<em>spotbugs:check</em> which is defined in pom.xml. Within Apache NetBeans this can
|
|
be accomplished by clicking JMRI in the <em>Projects</em> pane and then clicking
|
|
"spotbugs <strong>check</strong>" in the <em>Navigator</em> pane. When SpotBugs
|
|
completes, the Apache NetBeans Output window will show the SpotBugs results.</p>
|
|
|
|
<h2 id="loading_a_specific_branch_from_github">Loading a Specific Branch from GitHub</h2>
|
|
|
|
<p>The process for building from a branch (i.e. the one where someone has put a
|
|
change) is a bit different from the standard instructions. (The following is NetBeans
|
|
8.2, but it doesn’t vary with versions much)</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Under "Team" → "Remote" select "Fetch" (not Fetch from Upstream)<br>
|
|
<a href="images/38030695-285ba828-324e-11e8-8e73-7ff0f6c32125.png"><span class=
|
|
"image"><img src="images/38030695-285ba828-324e-11e8-8e73-7ff0f6c32125.png" alt=
|
|
"image"></span></a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Fill out the form to specify the correct user’s repository (After the 1st time
|
|
you do this, you’ll be able to select by name in the top choice)<br>
|
|
<a href="images/38030828-932040d8-324e-11e8-933f-cee0bf6f45e2.png"><span class=
|
|
"image"><img src="images/38030828-932040d8-324e-11e8-933f-cee0bf6f45e2.png" alt=
|
|
"image"></span></a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>On the next screen to select a branch, you can either select all of them
|
|
(there’s a button) or find and select just the name of the branch that holds the
|
|
desired change:<br>
|
|
<a href="images/38030974-fa9a7b52-324e-11e8-86f2-23c0c8735c9c.png"><img
|
|
src="images/38030974-fa9a7b52-324e-11e8-86f2-23c0c8735c9c.png" alt=
|
|
"image"></a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Click "Finish"</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>At this point, you’ve pulled my changes onto your local machine, but you’re not
|
|
using them yet. To have those files appear locally for Apache NetBeans to build:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Back on the main menu, select "Team" → "Checkout" → "Checkout Revision...". On
|
|
the window you get, click "Select":<br>
|
|
<a href="images/38031217-94948748-324f-11e8-8d61-8451af389d2e.png"><span class=
|
|
"image"><img src="images/38031217-94948748-324f-11e8-8d61-8451af389d2e.png" alt=
|
|
"image"></span></a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>In the upper left, find the imported branch you want, which in the example is
|
|
"bobjacobsen/ast-clock-power-bit". Either click to highlight (show) and then
|
|
click "Select", or just double-click on it. (Don’t worry about the upper right or
|
|
the lower box, they’ll be automatically set right)<br>
|
|
<a href="images/38031418-024b9f92-3250-11e8-9d52-aca1db8d4435.png"><span class=
|
|
"image"><img src="images/38031418-024b9f92-3250-11e8-9d52-aca1db8d4435.png" alt=
|
|
"image"></span></a></p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Back on the "Checkout Revision..." window, make sure the "Checkout as New
|
|
Branch" is <span class="underline">not</span> checked, and then click
|
|
"Checkout"</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<p>Now you’ve got a copy of my changes as your checked-out source. You should do a
|
|
"Clean and Build Project" to make sure that you get a consistent compilation, and
|
|
then you should be able to run it.</p>
|
|
|
|
<p class="important">
|
|
When you want to get back to the <em>standard</em> JMRI
|
|
version, from the main repository, you need to check out the <code>master</code>
|
|
branch. The process is similar, and simpler. Choose <span class=
|
|
"menuseq"><strong class="menu">Team</strong> <strong class=
|
|
"caret">›</strong> <strong class="submenu">Checkout</strong> <strong class=
|
|
"caret">›</strong> <strong class="menuitem">Checkout Revision...</strong></span>,
|
|
type <code>master</code> in the <em>Checkout Selected Revision</em> box, and
|
|
click <span class="textbutton">Checkout</span>.
|
|
</p>
|
|
|
|
<h2 id="NetBeansGuiForms">Using NetBeans "GUI-building" tools</h2>
|
|
<p>Several of JMRI's ".java" files have been defined using the NetBeans IDE
|
|
and its ability to create "forms" which use Java "Swing" components.
|
|
The NetBeans IDE provides a mechanism allows a developer to lay-out
|
|
the Swing components of a GUI object, generate the Java code from that
|
|
layout, and add the user-code to complete the implementation.
|
|
|
|
<p>This is
|
|
discussed in <a href='NetBeansGUIEditor.shtml'>JMRI Code: Using the
|
|
NetBeans Swing GUI Builder</a>.
|
|
|
|
<div id="footer-text">
|
|
Last updated 2022-11-10
|
|
</div>
|
|
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|