Serge NOEL
847 lines
42 KiB
Plaintext
847 lines
42 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 IntelliJ IDEA</title>
|
|
<meta name="author" content="Egbert Broerse">
|
|
<meta name="keywords" content="JMRI technical code IntelliJ IDEA 2017.2 2018 2019.1 2021.3 IDE">
|
|
<!--#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: Building with IntelliJ IDEA</h1>
|
|
|
|
<p>IntelliJ IDEA Community Edition (available from <a href=
|
|
"https://www.jetbrains.com/idea/">www.jetbrains.com/idea/</a>) makes a great platform for
|
|
working with JMRI and Java on macOS, Windows and *nix.<br>
|
|
Here we describe working with version 2023.x and up.</p>
|
|
|
|
<ul class="snav">
|
|
<!-- TOC -->
|
|
|
|
<li>
|
|
<a href="#install">Installation</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#getgit">Get Git</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ijprojectwin">The Project Window</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#push">Push changes</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#debug">Debugging (Setup)</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#tricks">Tricks</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#more">More</a>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>JMRI developers use Git for source control. Source control using Git is including as part
|
|
of the IntelliJ IDEA download. For more information for getting the JMRI source, see <a href=
|
|
"getgitcode.shtml">JMRI: Getting the Code</a>.</p>
|
|
|
|
<p>These instructions were first written and tested using IntelliJ IDEA 16 Community
|
|
Edition (CE). The current version is 2024.3 and the Community Edition is still free. This
|
|
page has been updated to reflect the 2022 version</p>
|
|
|
|
<h2 id="install">Installing IntelliJ IDEA</h2>
|
|
|
|
<h3>Preparations</h3>
|
|
|
|
<ol>
|
|
<li>Go to <a href="https://github.com/">GitHub.com</a> and create an account.
|
|
</li>
|
|
|
|
<li>In GitHub web, go to the JMRI/JMRI repo and "Fork" the JMRI repository to your own
|
|
remote copy. To do this, log on to your account at <a href=
|
|
"https://github.com/">GitHub.com</a> and navigate to the JMRI repository <a href=
|
|
"https://github.com/JMRI/JMRI">https://github.com/JMRI/JMRI</a> In the upper right-hand
|
|
corner of the page you will find a button labeled "Fork". Press the "Fork" button to create
|
|
your own repository of the JMRI source. (see <a href="getgitcode.shtml#get">Getting the
|
|
Code</a>).
|
|
</li>
|
|
</ol>
|
|
|
|
<p>After downloading and running the installer for your OS, configure the IntelliJ
|
|
application as follows:<br></p>
|
|
|
|
<h3 id="IjPrefs">Set Preferences</h3>
|
|
|
|
<p>Start IntelliJ and choose "Preferences..." from the application menu (macOS) or "Settings" from
|
|
the File menu (Win).</p>
|
|
|
|
<ol>
|
|
<li><span class="since">since 5.0 </span>From the Editor -> File Encodings tab, <strong>un</strong>check
|
|
"Transparent native-to-ascii conversion", because Java 11 allows UTF-8 character encoding for
|
|
those special accented letters found in many languages:<br>
|
|
<a href="images/IntelliJ/IjPrefsFileEncodings.png"><img src=
|
|
"images/IntelliJ/IjPrefsFileEncodings.png" alt="IntelliJ encoding prefs"></a>
|
|
</li>
|
|
|
|
<li>From the Version Control -> GitHub tab choose Add... (the + sign), and select
|
|
Log In with Token...<br>
|
|
<a href="images/IntelliJ/IjPrefsGitHubLogin.png"><img src=
|
|
"images/IntelliJ/IjPrefsGitHubLogin.png"
|
|
alt="IntelliJ build GitHub prefs"></a><br>
|
|
After you have created an account on GitHub, proceed by clicking
|
|
Generate... which will take you to your GitHub account web page.<br>
|
|
<a href="images/IntelliJ/IjPrefsAddGithub.png"><img src=
|
|
"images/IntelliJ/IjPrefsAddGithub.png" alt=
|
|
"IntelliJ build GitHub prefs"></a><br>
|
|
Choose the correct scope (repo, gist, read.org and workflow) and click the green
|
|
Generate Token button.<br>
|
|
Copy and paste this string into the IntelliJ Add GitHub Account dialog as your
|
|
Token and click Add Account.
|
|
</li>
|
|
|
|
<li>From the Build, Execution, Deployment -> Compiler -> Java Compiler tab, select "11"
|
|
as the Project bytecode version.<br>
|
|
On the same page, select "Eclipse" from the Use compiler drop-down:<br>
|
|
<a href="images/IntelliJ/IjPrefsJava11.png"><img src="images/IntelliJ/IjPrefsJava11.png"
|
|
alt="IntelliJ build java SDK prefs"></a>
|
|
</li>
|
|
|
|
<li>For now these are the essential settings. Some additional settings are described below, but for now
|
|
you can click OK to close your Preferences and start exploring the IDE.</li>
|
|
</ol>
|
|
|
|
<h2 id="getgit">Getting the JMRI Source using Git</h2>
|
|
|
|
<p>To get the source code from GitHub into IntelliJ, follow these steps:</p>
|
|
|
|
<ol>
|
|
<li>Open IntelliJ.</li>
|
|
|
|
<li>From the main menu bar select File -> New -> Project from Version Control ->
|
|
GitHub<br>
|
|
<a href="images/IntelliJ/IjImportMenu.png"><img src="images/IntelliJ/IjImportMenu.png"
|
|
alt="IntelliJ Git import pane"></a>
|
|
</li>
|
|
|
|
<li>If prompted, enter your GitHub username (Login) and Password in the authentication
|
|
fields and click "Login":<br>
|
|
<a href="images/IntelliJ/IjLoginGit.png"><img src="images/IntelliJ/IjLoginGit.png"
|
|
alt="IntelliJ git login"></a><br>
|
|
See <a href="#IjPrefs">IntelliJ Setup</a> above for detailed options to connect to GitHub.
|
|
</li>
|
|
|
|
<li>The Clone Repository pane should now appear. Select a Git Repository URL from your
|
|
account and point to your local repo folder as "Parent Directory":<br>
|
|
<a href="images/IntelliJ/IjCloneRepo.png"><img src="images/IntelliJ/IjCloneRepo.png"
|
|
alt="IntelliJ Git import pane3"></a><br>
|
|
Optionally click "Test" at top right to check your connection:<br>
|
|
<a href="images/IntelliJ/IjCloneTest.png"><img src="images/IntelliJ/IjCloneTest.png"
|
|
alt="IntelliJ Git import pane3"></a>
|
|
</li>
|
|
|
|
<li>Click "Clone" and follow progress in the indicator at the bottom of the Project
|
|
window:<br>
|
|
<a href="images/IntelliJ/IjCloningProgress.png"><img src=
|
|
"images/IntelliJ/IjCloningProgress.png"
|
|
alt="IntelliJ Git clone progress"></a>
|
|
</li>
|
|
|
|
<li>In the pane that opens after download is complete, check the location on disk,<br>
|
|
confirm the project name (like the original i.e. "JMRI") and click "Next":<br>
|
|
<a href="images/IntelliJ/IjImportProject1.png"><img src=
|
|
"images/IntelliJ/IjImportProject1.png" alt=
|
|
"IntelliJ Git import pane1"></a>
|
|
</li>
|
|
|
|
<li>Select "Create project from existing sources" and click "Next" again:<br>
|
|
<a href="images/IntelliJ/IjImportProject2.png"><img src=
|
|
"images/IntelliJ/IjImportProject2.png" alt=
|
|
"IntelliJ Git import pane2"></a>
|
|
</li>
|
|
|
|
<li>Click "Mark all" and then "Finish":<br>
|
|
<a href="images/IntelliJ/IjImportProject3.png"><img src=
|
|
"images/IntelliJ/IjImportProject3.png" alt=
|
|
"IntelliJ Git import pane3"></a>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>This will add JMRI to the IntelliJ Project window.</p>
|
|
|
|
<h2 id="ijprojectwin">The Project window</h2>
|
|
|
|
<p>After cloning is completed, the IntelliJ Project window should look like this (OS X
|
|
example):<br>
|
|
<a href="images/IntelliJ/IjProjectPanel.png"><img src="images/IntelliJ/IjProjectPanel.png"
|
|
alt="IntelliJ main project window"></a></p>
|
|
|
|
<p>Along the edges of the window are several groups of tools, often used are:</p>
|
|
|
|
<ol>
|
|
<li>the <strong>Project</strong> tab on the left</li>
|
|
|
|
<li>the <strong>JMRI</strong> directory in the left half</li>
|
|
|
|
<li>the <strong>Ant Build</strong> tab on the right and</li>
|
|
|
|
<li>the <strong>Version Control</strong> tab at the bottom.</li>
|
|
|
|
<li>the <strong>Git: master</strong> at the bottom right-hand corner, showing the current
|
|
Branch ("master") with a menu to change to another Branch.</li>
|
|
</ol>
|
|
|
|
<p>You can also access this panel from the main VCS -> Git -> Branches... menu or
|
|
right-clicking the JMRI Project folder and selecting Git -> Repository -> Branches...<br>
|
|
<a href="images/IntelliJ/IjGitRepoMenu.png"><img src="images/IntelliJ/IjGitRepoMenu.png"
|
|
alt="IntelliJ Project Git context menu"></a></p>
|
|
|
|
<p>To check out another Branch from the remote repo, select its name under "Remote Branches",
|
|
right-click and select "Checkout as new local branch":<br>
|
|
<a href="images/IntelliJ/IjNewBranch.png"><img src="images/IntelliJ/IjNewBranch.png"
|
|
alt="IntelliJ checkout branch"></a></p>
|
|
|
|
<p>When the information from the new Branch is downloaded, the Message Center will
|
|
confirm:<br>
|
|
<a href="images/IntelliJ/IjNewBranchMsg.png"><img src="images/IntelliJ/IjNewBranchMsg.png"
|
|
alt="IntelliJ checkout branch OK"></a></p>
|
|
|
|
<h3>Project Settings</h3>
|
|
<p><span class="since">since 5.0 </span>To ensure that the Java Development Kit version 11 you
|
|
intend to use for compiling JMRI is installed and will be used for this JMRI project, go to
|
|
File > Project Structure...<br>
|
|
<p>To manage the Java Development Kits available on your local computer, the
|
|
Platform Settings > SDKs tab allows downloading, renaming and uninstalling
|
|
JDKs as well as other packages such as Python:</p>
|
|
<div class="flex-container"><!-- flex is a set for responsive positioning on different screen sizes -->
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjPlatformSettings.png"><img src="images/IntelliJ/IjPlatformSettings.png"
|
|
alt="IntelliJ Platform dialog"></a></div>
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjPlatformDownloadJdk.png"><img src="images/IntelliJ/IjPlatformDownloadJdk.png"
|
|
alt="IntelliJ JDK dropdown"></a>
|
|
</div>
|
|
</div>
|
|
|
|
<p>Now switch to the Project Settings > Project tab, where you can select your
|
|
JDK of choice:</p>
|
|
<div class="flex-container"><!-- flex is a set for responsive positioning on different screen sizes -->
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjProjectSettingsSdkDropdown.png"><img
|
|
src="images/IntelliJ/IjProjectSettingsSdkDropdown.png"
|
|
alt="IntelliJ Project SDK menu"></a>
|
|
</div>
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjProjectSettingsSdk.png"><img src="images/IntelliJ/IjProjectSettingsSdk.png"
|
|
alt="IntelliJ Project settings for JMRI"></a>
|
|
</div>
|
|
</div>
|
|
<p>Click OK to close this dialog and apply the settings.</p>
|
|
|
|
<h3>Making Changes</h3>
|
|
|
|
<p>To work on the JMRI code, always start a new Branch so that your own "original" will stay
|
|
intact. In most cases, you will create this new branch off from <code>master</code>, your
|
|
personal copy of the main JMRI code.<br>
|
|
To create a new Branch in IntelliJ, first check out master. To make it current, first do VCS
|
|
> Git > Pull... from JMRI-master, and VCS > Git > Push... to create a current
|
|
base.<br>
|
|
Now then from the <strong>Git Branches</strong> pane, select "+ New Branch":<br>
|
|
<a href="images/IntelliJ/IjGitBranches.png"><img src="images/IntelliJ/IjGitBranches.png"
|
|
alt="IntelliJ main project window"></a><br>
|
|
Supply a name i.e. <code>my-dialog-2</code> and click OK.<br>
|
|
Note: Starting the name of your Branch with a unique two letter combination will make it stand out
|
|
from the long list much better than a name like <code>patch-1</code>.</p>
|
|
|
|
<p>In special cases, you might want to branch from one of your own active branches, or from a
|
|
different branch or Tag in the JMRI GitHub repository.<br>
|
|
To branch from a tag, select "Checkout Tag or Revision..." from the Git:branch dropdown at
|
|
bottom right:<br>
|
|
<img src="images/IntelliJ/IjGitCheckoutTag.png" alt=
|
|
"IntelliJ Checkout Tag option"><br>
|
|
In the dialog, start typing the name of the Tag you saw in GitHub web:<br>
|
|
<a href="images/IntelliJ/IjGitCheckoutTagDialog.png"><img src=
|
|
"images/IntelliJ/IjGitCheckoutTagDialog.png" alt=
|
|
"IntelliJ Checkout Tag dialog"></a><br>
|
|
Click "OK" and provide a name for the new branch.</p>
|
|
|
|
<h2 id="setant">Building and running JMRI using Ant</h2>
|
|
|
|
<p>We recommend that before you try to build and run one of the applications within IntelliJ,
|
|
you run the Ant Build -> <Default target> first. This will create the necessary
|
|
working directories, load some resource icons, and create needed Java files. To run the
|
|
<code>ant build.xml</code> do the following:</p>
|
|
|
|
<ol>
|
|
<li>Ant needs a JDK (Java Development Kit) in order to run the supplied "build.xml" file.
|
|
The IntelliJ IDEA download comes with a JDK, but you have to configure <code>ant</code>
|
|
to use the correct JDK.<br>
|
|
To verify the JDK is set to java 11, open the Ant Build tab [1] and select one of the items in the list.
|
|
Next, click the Properties button [2] at the top right of the pane and choose the Execution tab.<br>
|
|
As "Run under JDK:" select <strong>Project JDK (name as set in Project Structure)</strong> if not already
|
|
set:
|
|
<div class="flex-container"><!-- flex is a set for responsive positioning on different screen sizes -->
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjAntPropertiesOpen.png"><img src=
|
|
"images/IntelliJ/IjAntPropertiesOpen.png" alt=
|
|
"IntelliJ Ant menu"></a>
|
|
</div>
|
|
<div class="flex-item-50">
|
|
<a href=
|
|
"images/IntelliJ/IjAntBuildFilePropertiesPane.png"><img src=
|
|
"images/IntelliJ/IjAntBuildFilePropertiesPane.png" alt=
|
|
"IntelliJ Ant Settings"></a><br>
|
|
Click "OK" and save your JMRI Project (Cmd-S/Ctrl-S).
|
|
</div>
|
|
</div>
|
|
</li>
|
|
|
|
<li>Select a file in one of the JMRI ant folders in the Ant Build list,
|
|
right click, and
|
|
select "Run Target", simply double-click or press the green triangle "Run" button at the
|
|
top of the pane. This should start the ant build. Follow any messages in the Event Log that
|
|
pops up from the bottom edge of the Project window.</li>
|
|
|
|
<li>A new JMRI checkout should build cleanly. If not, do ant clean (meaning: double-click
|
|
the <strong>clean</strong> item on the Ant Built list) before contacting the <a href=
|
|
"https://jmri-developers.groups.io/g/jmri">jmri-developers.groups.io</a> for assistance.
|
|
</li>
|
|
</ol>
|
|
|
|
<p>If the ant build is successful, you can launch any of the JMRI applications from the Ant
|
|
Build tab.</p>
|
|
|
|
<h3 id="build">Building and running JMRI using IntelliJ</h3>
|
|
|
|
<p>To run an application, either:</p>
|
|
|
|
<ol>
|
|
<li>From the main menubar open the "Build" menu and select a JMRI package like
|
|
<code>panelpro</code> or</li>
|
|
|
|
<li>Open the Ant Build tab and from the "Ant Build" list, right-click the desired package
|
|
i.e. <code>decoderpro</code> and select "> Run Target".</li>
|
|
</ol>
|
|
|
|
<p>Note: The first two "JMRI" sets will build the English and French JHelpDev TOC & Index
|
|
files respectively. Hover your mouse over them and read the tooltip to learn which is
|
|
which.</p>
|
|
|
|
<p>The Messages Center Console will list all steps of the build process, after which a Java
|
|
icon will open with the application running including all your new edits.</p>
|
|
<!-- to do: write instructions for configurations? -->
|
|
|
|
<h2 id="push">Pushing changes to your GitHub branch</h2>
|
|
|
|
<p>The standard practice for getting your changes included in the main JMRI code repository
|
|
is to Commit them to your local repository periodically and, when ready to publish
|
|
everything, "Push" an entire set of Commits to your own remote repository on GitHub, and
|
|
finally make a Pull Request for the maintainers to "Pull" your changes into the main JMRI
|
|
repository.<br>
|
|
When working on more than one computer or different IDEs, Committing and Pushing makes your
|
|
new edit available on the other computers.<br>
|
|
See the <a href="GitFAQ.shtml">JMRI: Git FAQ</a> "Setting up a Git environment for JMRI
|
|
Developers" for more information.</p>
|
|
|
|
<h3>Pulling</h3>
|
|
|
|
<p>It is also good practice to "Pull" all recent changes from the main JMRI repository
|
|
before performing your Commits. After a "pull" your workspace and eventually your remote
|
|
GitHub repository will be in sync with the main JMRI repository, and you will see recent work
|
|
by others. To perform a "Pull":</p>
|
|
|
|
<ul>
|
|
<li>Select your project i.e. <strong>JMRI</strong> in the Project tab, right click and
|
|
select "Git" -> "Repository" -> "Pull..." from the context menu:<br>
|
|
<a href="images/IntelliJ/IjGitPullMenu.png"><img src="images/IntelliJ/IjGitPullMenu.png"
|
|
alt="IntelliJ Pull"></a><br>
|
|
or from the VCS menu select "Git" -> "Pull..."
|
|
</li>
|
|
|
|
<li>You may be asked first to confirm the origin of your remote repo, in our case
|
|
"JMRI/JMRI":<br>
|
|
<a href="images/IntelliJ/IjGitRemoteConfig.png"><img src=
|
|
"images/IntelliJ/IjGitRemoteConfig.png" alt=
|
|
"IntelliJ Pull options"></a>
|
|
</li>
|
|
|
|
<li>The Pull Changes dialog opens:<br>
|
|
<a href="images/IntelliJ/IjPullDialog.png"><img src="images/IntelliJ/IjPullDialog.png"
|
|
alt="IntelliJ Pull dialog"></a><br>
|
|
[1] Select a remote repository (depending on the way you want to manage that, either your
|
|
own repo or JMRI's as in the example).<br>
|
|
[2] From the displayed list, select the appropriate Branch to merge (you might also Pull
|
|
an extra Branch to switch to later).<br>
|
|
If what you expect is not in the list, click the Refresh button [3].
|
|
</li>
|
|
|
|
<li>To conclude, click "Pull" and answer how you would like to combine the new data into
|
|
the existing local repo:<br>
|
|
<a href="images/IntelliJ/IjPullOptionsdialog.png"><img src=
|
|
"images/IntelliJ/IjPullOptionsdialog.png" alt=
|
|
"IntelliJ Pull options"></a>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Pushing</h3>
|
|
|
|
<p>Pushing to your GitHub Branch:</p>
|
|
|
|
<ul>
|
|
<li>First, commit your changes to the local repository on your computer.<br>
|
|
To commit a set of changes, choose "Save All" from the Edit menu, select your project
|
|
i.e. <strong>JMRI</strong> in the Project tab, right click and select "Git" -> "Commit
|
|
Directory..." from the context menu:<br>
|
|
<a href="images/IntelliJ/IjCommitMenu1.png"><img src="images/IntelliJ/IjCommitMenu1.png"
|
|
alt="IntelliJ Commit menu"></a>
|
|
</li>
|
|
|
|
<li>In the Commit Changes pane, enter a Commit Message [1] describing your changes/fix
|
|
(line 1 will be used as the short title, add more detail from line 2).<br>
|
|
Select the files [2] you wish to commit and deselect files you don't.<br>
|
|
Choose your name from the list as Author [3]:<br>
|
|
<a href="images/IntelliJ/IjCommitPush2.png"><img src="images/IntelliJ/IjCommitPush2.png"
|
|
alt="IntelliJ Commit"></a>
|
|
</li>
|
|
|
|
<li>Click the "Commit" button [4] to add your saved edits to the local GitHub
|
|
Branch...</li>
|
|
|
|
<li>Or hover over the Commit button and choose "Commit and Push..." to continue to Push
|
|
this set of changes from your local repository to your remote repository on GitHub right
|
|
after the Commit (so others can access it and study it for inclusion into JMRI).<br>
|
|
<a href="images/IntelliJ/IjCommitPush.png"><img src="images/IntelliJ/IjCommitPush.png"
|
|
alt="IntelliJ Commit and Push"></a>
|
|
</li>
|
|
|
|
<li>In the Push Commits pane, review your description.<br>
|
|
For certain users there's an option to change the repo to which you want to push your
|
|
local branch to:<br>
|
|
<a href="images/IntelliJ/IjPushSelectRepoOrigin.png"><img src=
|
|
"images/IntelliJ/IjPushSelectRepoOrigin.png" alt=
|
|
"IntelliJ Push Dialog Option"></a><br>
|
|
Click on the underlined part of the top line to see that pop-up. You should push to a
|
|
(new) branch on "origin", your personal remote repository.<br>
|
|
If the path and all else is correct, click "Push".
|
|
</li>
|
|
|
|
<li>To push to your GitHub repository after a local Commit, just select "Push..." from the
|
|
"VCS" -> Git menu:<br>
|
|
<a href="images/IntelliJ/IjGitPushOptions.png"><img src=
|
|
"images/IntelliJ/IjGitPushOptions.png" alt=
|
|
"IntelliJ Push options"></a>
|
|
</li>
|
|
|
|
<li>If this went fine, a confirmation will appear at bottom left over the Version Control
|
|
tab:<br>
|
|
<a href="images/IntelliJ/IjVCSmenu.png"><img src="images/IntelliJ/IjVCSmenu.png"
|
|
alt="IntelliJ Push OK balloon"></a>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Before you can Push your changes to GitHub for the first time, you'll have to <a href=
|
|
"gitdeveloper.shtml#repo">create your own GitHub repository</a> (which you have already done
|
|
<a href="#install">in step 1</a>).</p>
|
|
|
|
<h2 id="debug">Debugging</h2>
|
|
|
|
<p>Check that the class and output paths have been set up correctly for the compiler. This
|
|
should happen automatically as part of the JMRI GitHub repository you copied at the start
|
|
(stored in the <code>.idea/JMRI .iml</code> file, see the <a href=
|
|
"https://www.jetbrains.com/help/idea/specifying-compilation-settings.html">IntelliJ
|
|
Compilation Settings help page</a>).</p>
|
|
|
|
<ol>
|
|
<li>In IntelliJ, select the <strong>File > Project Structure...</strong> menu item.</li>
|
|
|
|
<li>Select <strong>Modules</strong> under <strong>Project Settings</strong> on the
|
|
left.</li>
|
|
|
|
<li>Select the <strong>Sources</strong> tab on the right.</li>
|
|
|
|
<li>In the file tree, select the <strong>JMRI > java > src</strong> folder icon and
|
|
click on <strong>Mark as: <u>S</u>ources</strong> (the blue icon).<br>
|
|
<img src="images/IntelliJ/IjProjectSettingsSourcesStep1_class.png"
|
|
alt="IntelliJ Project Setting Sources tab - sources"></li>
|
|
|
|
<li>Repeat for the test classes by selecting <strong>JMRI > java > test</strong> and
|
|
clicking on the green <strong>Mark as: <u>T</u>ests</strong> icon.<br>
|
|
<img src="images/IntelliJ/IjProjectSettingsSourcesStep2_tests.png"
|
|
alt="IntelliJ Project Setting Sources tab - tests"></li>
|
|
|
|
<li>In the column to the right both choices will be visible:<br>
|
|
<a href="images/IntelliJ/IjProjectJmriSetting1ModulesPaths.png"><img src=
|
|
"images/IntelliJ/IjProjectJmriSetting1ModulesPaths.png" alt=
|
|
"JMRI Project Settings - Build - Compiler Output Paths screen"></a><br>
|
|
From now on you will also see these special icons in the Project file listing:
|
|
<a href="images/IntelliJ/IjProjectCompilepathsSet.png"><img src=
|
|
"images/IntelliJ/IjProjectCompilepathsSet.png" alt=
|
|
"SRC and TEST folders highlighted in Ij Project File List"></a>
|
|
</li>
|
|
|
|
<li>From the <strong>Build</strong> menu select <strong>Build Project</strong> or
|
|
<strong>Build Module 'JMRI'</strong> (and wait a couple of minutes, do some stretch
|
|
exercises in the meantime).</li>
|
|
</ol>
|
|
|
|
<p>We've documented the following steps to help you get started using the built-in Debug
|
|
tool. We tested the JMRI project with the JAR, Application and JUnit (test) Templates.</p>
|
|
|
|
<ol>
|
|
<li>In IntelliJ, start by opening Preferences > Build, Execution, Deployment and check
|
|
"Generate debugging info":<br>
|
|
<a href="images/IntelliJ/IjDebugPrefs.png"><img src="images/IntelliJ/IjDebugPrefs.png"
|
|
alt="IntelliJ Preferences - Build - Java Compiler screen"></a>
|
|
</li>
|
|
|
|
<li>Choose "Debug..." from the Run menu:<br>
|
|
<a href="images/IntelliJ/IjDebug1Menu.png"><img src="images/IntelliJ/IjDebug1Menu.png"
|
|
alt="IntelliJ Debug - Run menu"></a><br>
|
|
On the small "Debug" pane that appears, click "Edit Configurations..."<br>
|
|
Alternatively, on the top right, click on "Add Configuration...":<br>
|
|
<img src="images/IntelliJ/IjDebug1Button.png" alt=
|
|
"IntelliJ Debug/Run Configuration pane">
|
|
</li>
|
|
|
|
<li>On the top left of the new pane that appears, click the + sign (Add New
|
|
Configuration).<br>
|
|
<img src="images/IntelliJ/IjDebug2Plus.png" alt=
|
|
"IntelliJ Debug/Run Configuration - New button"><br>
|
|
Or simply type Command + N.<br>
|
|
Select "JAR Application" in the list.</li>
|
|
|
|
<li>This opens the "Run/Debug Configurations" pane:<br>
|
|
<a href="images/IntelliJ/IjDebug3ConfigPaneJar.png"><img src=
|
|
"images/IntelliJ/IjDebug3ConfigPaneJar.png" alt=
|
|
"IntelliJ Debug/Run Configuration - Edit New Config pane"></a><br>
|
|
|
|
<ul>
|
|
<li>As the Name of this Configuration, enter somethong like "JMRI DP debug".</li>
|
|
|
|
<li>Make sure "Build" is visible in the "Before launch:" table, select "Run Ant target"
|
|
and choose "jar" from the build.xml list<br>
|
|
In case of a JUnit template, opt for "build" instead.</li>
|
|
|
|
<li>Check "Activate tool window" near the bottom of the pane.</li>
|
|
|
|
<li>Enter <strong>"jmri.jar"</strong> as the "Path to JAR" or use the "..." button to
|
|
navigate to the freshly built <code>jmri.jar</code> in your Project.</li>
|
|
|
|
<li>Make sure the prefilled "Working directory:" is showing your local path to JMRI
|
|
(see example).<br>
|
|
As the "JRE:" choice set "Default (1.8)".</li>
|
|
|
|
<li>Select "JMRI" using the "Search sources using module's classpath:" drop down.</li>
|
|
|
|
<li>Click "OK" to complete the configuration setup.</li>
|
|
</ul>
|
|
Here's another example, showing a JUnit template filled in for a single class. For
|
|
coverage, "Fork mode" must be set to "none" on the Configuration tab. Choose IntellJ as
|
|
the code coverage runner on the Code Coverage tab, and don't forget to fill in the
|
|
class(es) you want to have checked for coverage, see 2.:
|
|
<div class="flex-container"><!-- flex is a set for responsive positioning on different screen sizes -->
|
|
<div class="flex-item-50">
|
|
<a href="images/IntelliJ/IjDebugConfigJunit1.png"><img src=
|
|
"images/IntelliJ/IjDebugConfigJunit1.png" alt=
|
|
"IntelliJ Debug/Run Configuration - Edit New Config pane"></a>
|
|
</div>
|
|
<div class="flex-item-50">
|
|
<a href=
|
|
"images/IntelliJ/IjDebugConfigJunit2.png"><img src=
|
|
"images/IntelliJ/IjDebugConfigJunit2.png" alt=
|
|
"IntelliJ Debug/Run Configuration - Edit New Config pane"></a>
|
|
</div>
|
|
</div>
|
|
</li>
|
|
|
|
<li>To run a debug session, start by opening a .java file and set a Breakpoint on a line in
|
|
your code by clicking in the left margin of the central edit pane:<br>
|
|
<img src="images/IntelliJ/IjDebug5Breakpoint.png" alt=
|
|
"IntelliJ Debug Breakpoint in margin"></li>
|
|
|
|
<li>We're now ready to start a Debug session by clicking the Bug button at the top right,
|
|
making sure our "JMRI DP debug" configuration is selected in the drop down to the left of
|
|
it:<br>
|
|
<img src="images/IntelliJ/IjDebug4StartDebug.png" alt=
|
|
"IntelliJ Debug select your config set"></li>
|
|
|
|
<li>After a while, at the bottom of the main IntelliJ IDE interface, the Debug pane
|
|
appears, stopping just before your Breakpoint or an Exception:<br>
|
|
<a href="images/IntelliJ/IjDebug6DebugInterface.png"><img src=
|
|
"images/IntelliJ/IjDebug6DebugInterface.png" alt=
|
|
"IntelliJ Debug code execution stopped at Breakpoint"></a>
|
|
</li>
|
|
|
|
<li>Inspect the current values of the active variables, and click the Step Into button to
|
|
execute 1 line of code:<br>
|
|
<img src="images/IntelliJ/IjDebug7StepInto.png" alt=
|
|
"IntelliJ Debug Step Into buttons"></li>
|
|
</ol>
|
|
|
|
<p>A further explanation of this pane and debugging in general can be found in the <a href=
|
|
"https://www.jetbrains.com/help/idea/debugging.html">IntelliJ Online Help</a>.<br>
|
|
If your code was not compiled just before debugging, the source and class files might be out
|
|
of sync, so be sure to build first. As described above, you could add that to your Debug
|
|
Configuration too, but it might take unneeded extra time before each run.</p>
|
|
|
|
<h3 id="test">Testing with IntelliJ</h3>
|
|
|
|
<p>Besides Debug, there's also a "Run ... with Coverage" option available in the Run menu and
|
|
toolbar.</p>
|
|
|
|
<p>When you create or edit a <a href="JUnit.shtml">test</a> (located in your Project at
|
|
JMRI.java.test etc.) you can test it in one of the following ways:</p>
|
|
|
|
<ul>
|
|
<li>part of the <code>alltest</code> Ant Build (double-click in the IntelliJ Ant Build
|
|
right hand column to run)</li>
|
|
|
|
<li>run it on its own using the <code>test-single</code> Ant Task</li>
|
|
|
|
<li>create a JUnit type <a href="#debug">Debug Configuration</a> with optional Coverage
|
|
reporting or
|
|
</li>
|
|
|
|
<li>Run a single test inside the File Edit pane of an open test file (the simplest to set
|
|
up)</li>
|
|
</ul>
|
|
|
|
<p>To use <code>test-single</code>, enter the path of your test in the Ant Build Properties
|
|
by either clicking the Properties button at the top or right-clicking on any line in the Ant
|
|
Build column, choosing "Properties". Open the "Properties" tab, click the + (Add) sign at
|
|
lower left and enter <code>test.includes</code> in the Name column and the path to your test
|
|
under Value, starting with either <code>apps.</code> or <code>jmri.</code> as shown:<br>
|
|
<a href="images/IntelliJ/IjAntProps.png"><img src="images/IntelliJ/IjAntProps.png"
|
|
alt="IntelliJ Ant Property"></a></p>
|
|
|
|
<p>The Code Coverage of your test can be checked by running Debug With Coverage. Unless you
|
|
install the Jacoco application, IntelliJ runs its own coverage scheme:<br>
|
|
After tests have completed the Coverage pane opens. Double-click a class line to open the
|
|
code page. In the left margin coverage is marked:<br>
|
|
<a href="images/IntelliJ/IjCoverageResultPane.png"><img src=
|
|
"images/IntelliJ/IjCoverageResultPane.png" alt=
|
|
"IntelliJ Ant Property"></a></p>
|
|
|
|
<p>To run a single <code>@Test</code> test inside the file window, make sure you have set up
|
|
the JMRI Project Structure > Modules > Sources (see <a href="#debug">above</a>). When
|
|
you open a Test file, in the left margin a green Run Test arrow will show next to every test.
|
|
Click it and select one of the 3 options from the combo:<br>
|
|
<a href="images/IntelliJ/IjFileRunTestIcon.png"><img src=
|
|
"images/IntelliJ/IjFileRunTestIcon.png" alt=
|
|
"IntelliJ Run @Test"></a></p>
|
|
|
|
<h2 id="spotbugs">Running SpotBugs</h2>
|
|
|
|
<ol>
|
|
<li>Confirm that the class and output paths have been <a href="#debug">set up correctly</a>
|
|
for the compiler.
|
|
</li>
|
|
|
|
<li>An IntelliJ SpotBugs plug-in is not yet available, so you run it as an Ant Build task
|
|
and study the .html report.<br>
|
|
To add the path to SpotBugs for Ant in your <code>local.properties</code> file to match
|
|
the place where the SpotBugs application is located on your computer add these lines:<br>
|
|
<code># configure SpotBugs<br>
|
|
spotbugs.home=/Users/you/Apps/spotbugs-4.2.3</code><br>
|
|
See the <a href="SpotBugs.shtml">JMRI SpotBugs help</a>.
|
|
</li>
|
|
|
|
<li>Next, from the <strong>Ant</strong> tab select the <strong>(3rd) JMRI > spotbugs</strong>
|
|
task, wait a couple of minutes (do some stretch exercises etc.), followed by SpotBugs
|
|
doings its duty. The analysis results show up as an html page called <code>spotbugs.html</code>
|
|
that is placed in the root of the JMRI Module on the Project tab.<br>
|
|
Right click to open it with your favorite browser.</li>
|
|
<!-- update once a plugin is available for SpotBugs:
|
|
|
|
<li>When you right-click on any file icon in the
|
|
<code>src</code> or <code>test</code> folders, the
|
|
<b>SpotBugs</b> context menu allows you to <b>Analyze Selected File(s)</b> and more:<br>
|
|
<img src="images/IntelliJ/IjFbContextMenuOnFile.png"
|
|
alt="SpotBugs context menu">
|
|
<img src="images/IntelliJ/IjSpotbugsToolbar.png"
|
|
alt="SpotBugs Plug-In toolbar active"><br>
|
|
The Bugs toolbar provides access to the same functions, ranging from file to class, package, Module and
|
|
scope.<br>
|
|
A bit lower in the context menu the <b>Rebuild</b> and <b>Build Module</b> items should also become
|
|
active.</li>
|
|
<li>Either choice will start a compilation of the classes involved, followed by SpotBugs analyzing the
|
|
code structure. Watch the progress bar either at the bottom of the IntelliJ window or in a dialog:<br>
|
|
<img src="images/IntelliJ/IjFbProgressbar.png"
|
|
alt="SpotBugs Analysis progress dialog">
|
|
<img src="images/IntelliJ/IjBuildtaskProgressbar.png"
|
|
alt="SpotBugs background task indicator">
|
|
</li>
|
|
<li>Once the SpotBugs analysis has completed, its tab pane at bottom left in IntelliJ at the JI (bug) icon will
|
|
show one or more bugs.<br>
|
|
Click <b>more...</b> to see a summary of your settings.<br>
|
|
Browse the bugs, code preview bug details and suggested fixes (click image to enlarge):<br>
|
|
<a href="images/IntelliJ/IjFbAnalysisDetails.png"><img
|
|
src="images/IntelliJ/IjFbAnalysisDetails.png"
|
|
alt="SpotBugs plugin in action"></a>
|
|
</li> -->
|
|
</ol>
|
|
|
|
<p>For additional resources check the official <a href=
|
|
"https://spotbugs.readthedocs.io/en/stable/installing.html">SpotBugs Help</a></p>
|
|
|
|
<h2>Making a Pull Request</h2>
|
|
|
|
<p>When your contribution is ready, submit a "Pull Request" to the main JMRI code repository
|
|
on the GitHub website so the maintainers of JMRI can study your proposed changes and merge
|
|
them into the master JMRI repo.</p>
|
|
|
|
<p>To make a PR from within IntelliJ IDEA, select "Create Pull Request" from the "VCS" ->
|
|
"Git" menu (it's the one but last item, supported by the Git plugin).<br>
|
|
Note: Be sure to select your own repository <code>origin:</code> if you see multiple options
|
|
to choose from in this submenu:<br>
|
|
<img src="images/IntelliJ/IjGitPRViaOwnRepo.png" alt=
|
|
"IntelliJ Git Menu"></p>
|
|
|
|
<p>Fill in a title and comment for your PR:<br>
|
|
<a href="images/IntelliJ/IjGitPRCreate.png"><img src="images/IntelliJ/IjGitPRCreate.png"
|
|
alt="IntelliJ Git Create PR"></a></p>
|
|
|
|
<p>Unless your change is intended for a special branch like a previous release, you would set
|
|
the PR Target Branch to "master" as shown above. Otherwise, use the combo box to change the
|
|
branch where you want your new changes to be added:<br>
|
|
<a href="images/IntelliJ/IjGitCreatePrSelectBaseBranch.png"><img src=
|
|
"images/IntelliJ/IjGitCreatePrSelectBaseBranch.png" alt=
|
|
"IntelliJ Git Create PR Base Branch"></a></p>
|
|
|
|
<p>To create a PR from GitHub web - outside IntelliJ - start by signing on to the <a href=
|
|
"https://github.com">GitHub website</a>, selecting your repository & branch and clicking the
|
|
<a href="gitdeveloper.shtml#pull">Pull Request button</a>. For more info, see the <a href=
|
|
"gitdeveloper.shtml#pull">Git Developer Help</a> page.</p>
|
|
|
|
<h3 id="tricks">Tricks</h3>
|
|
|
|
<h4>Edit .properties files</h4>
|
|
|
|
<p class="important">Before you start, make sure you have set up IntelliJ to convert special
|
|
characters using <strong>lower case</strong> encoding strings, as only then will your changes
|
|
be accepted for merging into JMRI.<br>
|
|
The instructions to set this via <code>vmoptions</code> are <a href="#install">at the top of
|
|
this page</a>.<br>
|
|
In addition, check that in the IntelliJ Preferences > Editor > Code Style >
|
|
Properties you checked "Insert space around key-value delimiter", or your edits will mess up
|
|
the work already in place.</p>
|
|
<a href="images/IntelliJ/IjPrefsEditorProperties.png"><img src=
|
|
"images/IntelliJ/IjPrefsEditorProperties.png" alt=
|
|
"IntelliJ Props Editor Style Setting"></a>
|
|
<p>To easily edit Resource Bundle <code>.properties</code> files, select a 'Bundle' header icon in the Project file list and type Cmd +
|
|
arrow down key, or double click one of the language files. This will initially open a window with just that
|
|
single language file in the editor window.<br>
|
|
To access a single view with the list of coded keywords on the left and text boxes for every
|
|
translation into a different language to the right, on IntelliJ 2022 install the Resource Bundle Editor
|
|
plugin (go to Preferences > Plugins, see screen shot).<br>
|
|
<img src="images/IntelliJ/IjEditProperties.png" alt="IntelliJ RBE Plugin"></p>
|
|
<a href="images/IntelliJ/IjEditProperties.png"><img src=
|
|
"images/IntelliJ/IjEditProperties.png" alt=
|
|
"IntelliJ Bundle edit window"></a>
|
|
|
|
<p>When you open a specific language file and you have the Resource Bundle Editor installed, at the
|
|
bottom of the screen you can switch views by clicking the <strong>Resource Bundle</strong> or the
|
|
<strong>Text</strong> tab:<br>
|
|
<img src="images/IntelliJ/IjResourceJump.png" alt=
|
|
"IntelliJ Bundle edit menu"></p>
|
|
|
|
<h4>Reset HEAD</h4>
|
|
|
|
<p>When in testing your app you conclude that you would like to remove your last couple of
|
|
Commits, IntelliJ gives you the option to graphically Reset your HEAD.<br>
|
|
To do this, open the "Version Control" -> "Log" tab at the lower left of the Project
|
|
window to view a "Track Plan" of the history of your Branch, all the way back to the
|
|
different parts that made JMRI:<br>
|
|
<a href="images/IntelliJ/IjVersionControlPane.png"><img src=
|
|
"images/IntelliJ/IjVersionControlPane.png" alt=
|
|
"IntelliJ Version Control tab"></a></p>
|
|
|
|
<p>Click on any line to view the changes that were Committed at that point in time (listed to
|
|
the right).<br>
|
|
To reset your repo (HEAD) back to a certain point, right-click on the corresponding line and
|
|
select "Reset Current Branch to Here..." (and confirm).<br>
|
|
<a href="images/IntelliJ/IjResetBranchTo.png"><img src="images/IntelliJ/IjResetBranchTo.png"
|
|
alt="IntelliJ History reset"></a><br>
|
|
Confirm the way you want to save or discard your Commits after that point in the dialog:<br>
|
|
<a href="images/IntelliJ/IjResetBranchDialog.png"><img src=
|
|
"images/IntelliJ/IjResetBranchDialog.png" alt=
|
|
"IntelliJ Reset HEAD dialog"></a></p>
|
|
|
|
<h4>Master password</h4>
|
|
|
|
<p>To securely store your GitHub login, you might periodically be asked to unlock it:<br>
|
|
<a href="images/IntelliJ/IjMasterPasswd.png"><img src="images/IntelliJ/IjMasterPasswd.png"
|
|
alt="IntelliJ Git Master Pwd dialog"></a></p>
|
|
|
|
<h4>Error: Can't start Git</h4>
|
|
|
|
<p>On macOS, when you run into this error, usually when starting IntelliJ for the first time
|
|
after a system update:<br>
|
|
<a href="images/IntelliJ/IjXcodeGitProblem1.png"><img src=
|
|
"images/IntelliJ/IjXcodeGitProblem1.png" alt=
|
|
"IntelliJ Git error"></a></p>
|
|
|
|
<ol>
|
|
<li>Quit and restart IntelliJ</li>
|
|
|
|
<li>If that does not fix it, quit IntelliJ and start the Apple Xcode application.<br>
|
|
You will be asked to agree with its licence agreement, and that will reenable the Git
|
|
installation to be used inside IntelliJ as well as Xcode.<br>
|
|
<a href="images/IntelliJ/IjXcode1.png"><img src="images/IntelliJ/IjXcode1.png"
|
|
alt="IntelliJ Git error"></a>
|
|
</li>
|
|
</ol>
|
|
|
|
<h4>Run/Debug Error</h4>
|
|
|
|
<p>When you click <strong>Debug</strong> with a configuration selected (at top right) you
|
|
might see a <em>path not found. name: com.intellij.rt.debugger.agent.CaptureAgent</em> with
|
|
the Debug Variables pane showing: "Frame is not available". This is caused by an accidental
|
|
exception breakpoint on ClassNotFoundException. Open <strong>View Breakpoints...</strong>
|
|
from the <strong>Run</strong> menu and uncheck the breakpoint under "Java Exception
|
|
Breakpoints". We fixed it by unchecking the red lightning symbol in the margin of the
|
|
<code>loadClass</code> code listing. (source: <a href=
|
|
"https://stackoverflow.com/questions/27820035/intellij-idea-classnotfoundexception-if-run-debug-execution-run-does-work">
|
|
Stack Overflow</a>)</p>
|
|
<!-- to do suppress errors
|
|
<a ></a>
|
|
<h2 id="errors">Compiler Errors and Warnings</h2>
|
|
|
|
The default IntelliJ compiler configuration may produce some unnecessary
|
|
warnings. You can adjust the warnings to match the screenshots as
|
|
shown below by going to Window -> Preferences and selecting
|
|
"Java -> Compiler -> Errors/Warnings".
|
|
-->
|
|
|
|
<h4>Run/Debug Error</h4>
|
|
<p>If you see a message similar to this:<br>
|
|
<a href="images/IntelliJ/IjAntErrorDialog.png"><img src="images/IntelliJ/IjAntErrorDialog.png"
|
|
alt="IntelliJ Ant error"></a><br>
|
|
it means the SDK name as set in the Project Structure > Project Settings > SDK tab does not match any of
|
|
the JDKs installed. Fix it by choosing a different Java 11 JDK as described <a href="#setant">above</a>.
|
|
</p>
|
|
|
|
<h2 id="more">More Help</h2>
|
|
|
|
<p>See the IntelliJ IDEA <a href="https://www.jetbrains.com/help/idea/getting-started.html">web
|
|
reference</a> for more specific information on using this IDE.</p>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|