Serge NOEL
334 lines
15 KiB
Plaintext
334 lines
15 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 Eclipse</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="keywords" content="JMRI technical code Eclipse">
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<body>
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI Code: Building with Eclipse</h1>
|
|
|
|
<p>
|
|
Eclipse (available at <a href="https://www.eclipse.org/">www.eclipse.org</a>) can be used
|
|
for working with JMRI. <a href="NetBeans.shtml">NetBeans</a> is recommended unless you are
|
|
already familiar with Eclipse.
|
|
</p>
|
|
|
|
<p>
|
|
Eclipse is a complex environment to work with. If you're already familiar with IDEs like
|
|
Microsoft Visual Studio it won't be too hard to get used to, but it is definitely worth
|
|
buying a textbook (e.g. <a
|
|
href="https://www.amazon.com/exec/obidos/tg/detail/-/0321305027/qid=1124158635">The
|
|
Java Developer's Guide to Eclipse</a>).
|
|
</p>
|
|
|
|
<p>
|
|
JMRI developers use Git for source control. Source control using Git has been included as
|
|
part of the Eclipse since the "Oxygen" download in 2017. For more information or an
|
|
alternate method for getting the JMRI source, see <a href="getgitcode.shtml">JMRI:
|
|
Getting the Code</a>.
|
|
</p>
|
|
|
|
<p>These instructions were developed and tested using "Eclipse IDE for Java Developers"
|
|
version "Oxygen Release (4.7.0)" and have been updated as of September of 2023.</p>
|
|
|
|
<p>
|
|
Note that you must also install a <strong>Java Development Kit (JDK)</strong> Java version
|
|
11 (not included with Eclipse) to build JMRI with Eclipse.
|
|
</p>
|
|
|
|
<p>Also note that since version 4.99 JMRI requires Java version 11. You must confirm that
|
|
JRE 11 is the default Java Runtime Environment.</p>
|
|
|
|
<h2 id="getgit">Eclipse version "Proton" and later</h2>
|
|
<p>The "Proton" and later versions of Eclipse require a Maven project update after
|
|
downloading the JMRI source files. To do this, right click "jmri [...]" in the Package
|
|
Explorer, then in the menu, select "Maven" and in the sub menu "Update project ...". After
|
|
the update is complete, do a project clean to rebuild the source files.</p>
|
|
|
|
<h2>Getting the JMRI Source using Git</h2>
|
|
<p>To get the source code from GitHub using Git you need to do the following:</p>
|
|
<ol>
|
|
<li>Go to <a href="https://github.com/">GitHub.com</a> and create an account.
|
|
</li>
|
|
|
|
<li>Then open Eclipse.</li>
|
|
|
|
<li>From the main menu bar select "File" then "Import..."</li>
|
|
|
|
<li>Click on "Git" then "Project from Git" then the "Next" button.</li>
|
|
|
|
<li>Now select the repository source by clicking on "Clone URI". The Source Git
|
|
Repository screen should appear.</li>
|
|
</ol>
|
|
<a href="images/EclipseSourceGitRepository.png"><img
|
|
src="images/EclipseSourceGitRepository.png" alt="Eclipse Git pane"></a>
|
|
<ol>
|
|
<li>Enter the URI "https://github.com/JMRI/JMRI".</li>
|
|
|
|
<li>Enter your GitHub user name and password in the authentication fields.</li>
|
|
|
|
<li>Click the "Next" button and the Branch Selection screen should appear.</li>
|
|
</ol>
|
|
<a href="images/EclipseGitBranchSelection.png"><img
|
|
src="images/EclipseGitBranchSelection.png" alt="Eclipse Branch pane"></a>
|
|
<ol>
|
|
<li>Select the branches you want to install. If you're not sure which branches you
|
|
need, select just the "master" branch. This branch contains the latest code for JMRI.</li>
|
|
|
|
<li>Click the "Next" button and the Local Destination screen should appear.</li>
|
|
|
|
<li>Press the "Next" button if the local destination is acceptable to you.</li>
|
|
|
|
<li>The download will now happen. It might take a while.</li>
|
|
|
|
<li>After the download completes, select "Import existing Eclipse projects" under the
|
|
"Wizard for project import", then "Next".</li>
|
|
|
|
<li>Select "Finish" to complete the import.</li>
|
|
</ol>
|
|
|
|
<p>After the import is complete the Eclipse Package Explorer should look like this:</p>
|
|
<a href="images/EclipsePackageExplorer.png"><img src="images/EclipsePackageExplorer.png"
|
|
alt="Eclipse Package Explorer pane"></a>
|
|
<p>Note that the first build can take a while and will require Internet access.</p>
|
|
|
|
<p>If you get the error "Cannot read lifecycle mapping for artifact", open the "Run" menu,
|
|
select "Run As", and then select "Maven generate-sources" to fix the error and start the
|
|
first build.</p>
|
|
|
|
<p>To run an application do the following:</p>
|
|
|
|
<ol>
|
|
<li>From the "Run" menu, select "Run Configurations..."</li>
|
|
|
|
<li>On the left side, expand "Maven Build".</li>
|
|
|
|
<li>Select "JMRI DecoderPro" or "JMRI PanelPro".</li>
|
|
|
|
<li>Optional, select the "Common" tab, the section on "Display in favorites menu",
|
|
check the box next to "Run"</li>
|
|
|
|
<li>Click "Run" to run the application. Eclipse will retain the build in the Run menu.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
To run an application native to Eclipse you might need the communication library. For for
|
|
the application you want to run, select the "Arguments" tab, and under VM argments enter
|
|
(You should probably cut and paste): If you're using a 32 bit windows system add the library
|
|
path:<br>
|
|
<code>-Djava.library.path=.;lib;lib/windows/x86</code>
|
|
</p>
|
|
<p>
|
|
Note if you're using a 64 bit windows system change the library path to:<br>
|
|
<code>-Djava.library.path=.;lib;lib/windows/x64</code>
|
|
</p>
|
|
<p>If during the launch of DecoderPro or PanelPro the program hangs, or errors are
|
|
reported to the console, there's a good chance that the META-INT files weren't created. To
|
|
fix, run the Ant "build.xml" as described below with only two targets selected, "realclean"
|
|
followed by "tests".</p>
|
|
|
|
<p>We also recommend that you deselect "Scrub output folders when cleaning projects" found
|
|
under Window->Preferences->Java->Compiler->Building Output folder. This keeps
|
|
the META-INT files in place after they are created by the Ant build.</p>
|
|
|
|
<p>Afterwards refresh the project, and if necessary do a project clean. The refresh should
|
|
fire off a build and hopefully cleanup the errors.</p>
|
|
|
|
<h2>Building and running JMRI using Ant</h2>
|
|
|
|
<ol>
|
|
<li>Ant needs a JDK (Java Development Kit) in order to run the supplied "build.xml"
|
|
file. The Eclipse download doesn't include a JDK, so you must download and install a JDK,
|
|
and then configure Ant to use the JDK.</li>
|
|
|
|
<li>Select the build.xml file using the Package Explorer, then right click, and a menu
|
|
should appear.</li>
|
|
|
|
<li>Now select "Run As" then "2 Ant Build".</li>
|
|
|
|
<li>Confirm under the menu tab "JRE" that you've selected a JDK, not a JRE.</li>
|
|
|
|
<li>Now press the "Run" button, this should start the Ant build.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
If the Ant build fails, most likely it is because you need a JDK (Java Development Kit)
|
|
rather than a JRE (Java Runtime Environment) which is the default. To change the JRE, select
|
|
"Run As" "2 Ant Build" and a new window should appear. Select the "JRE" tab. The change the
|
|
JRE, select the "Separate JRE:" radio button, and then press the "Installed JREs" button. If
|
|
you don't see a JDK, you need to add one (from site above).<br> A new JMRI checkout
|
|
should build cleanly. If not, please check with the JMRIusers or jmri-developers mailings
|
|
lists for help.
|
|
</p>
|
|
|
|
<p>If the Ant build succeeds, you can now launch any of the JMRI applications from Ant,
|
|
and create a jmri.jar file if you wish. Use the "2 Ant Build" and in the window select the
|
|
"Targets" tab, and use the appropriate checkbox to generate what you want. Two targets that
|
|
are worth running if you're experiencing error messages in the Eclipse console window are
|
|
"realclean" followed by "tests".</p>
|
|
|
|
<h2 id="build">Pushing changes to your GitHub branch</h2>
|
|
|
|
<p>
|
|
The standard practice for getting your changes included in main JMRI code repository is to
|
|
commit them to your local repository periodically, then when ready to publish "push" an
|
|
entire set of changes to a repository belonging to you on GitHub, and then finally making a
|
|
request for somebody to "pull" your changes into the main JMRI repository. See <a
|
|
href="GitFAQ.shtml">JMRI: Git FAQ</a> "Setting up a Git environment for JMRI Developers"
|
|
for more information.
|
|
</p>
|
|
|
|
<p>It is also good practice to "pull" all of the 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 synch with the main JMRI repository. To perform a "pull"
|
|
select your project, then "Team" then "Pull" from the menu.</p>
|
|
|
|
<p>If you want to see which files are going to be modified before the "Pull", you can use
|
|
the "Team Synchronizing" feature. To do so, right click on your project, the "Team" then
|
|
"Synchronize Workspace"</p>
|
|
|
|
<p>Pushing to your GitHub branch:</p>
|
|
|
|
<ul>
|
|
<li>First, commit your changes to the local repository on your computer
|
|
<p>To commit a set of changes, right click on the project that you want to commit, and
|
|
select "Team" followed by "Commit". Enter a commit message and select the files you wish
|
|
to commit.</p>
|
|
</li>
|
|
|
|
<li>Next, "push" a set of changes from your local repository to your repository on
|
|
GitHub. (You do this so others can access it and pick it up for inclusion into JMRI)
|
|
<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 may
|
|
have done above) and "fork" the JMRI repository. Log on to your account at <a
|
|
href="https://github.com/">GitHub.com</a> and then 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.
|
|
</p>
|
|
|
|
<p>To push to your GitHub repository, again select "Team" then "Remote" then
|
|
"Configure Push to Upstream". In the "Configure Push" window, click on the "Push URIs"
|
|
and then the "Add" button. In the "New URI" window enter the URL of your GitHub
|
|
repository along with your username and password. After pressing "Finish" the "Configure
|
|
Push" window should look like the image below:</p> <a href="images/EclipseConfigurePush.png"><img
|
|
src="images/EclipseConfigurePush.png" alt="Eclipse Error pane"></a>
|
|
|
|
<p>Press either the "Save and Push" or the "Save" button. Later when you want to push
|
|
new changes to your repository on GitHub, you can simply commit them as described above,
|
|
and then use the "Push" icon in the Synchronize window.</p>
|
|
</li>
|
|
|
|
<li>Finally, submit a "Pull Request" to the main JMRI code repository on the GitHub
|
|
website.
|
|
<p>
|
|
To do this, start by signing on to the <a href="https://github.com">GitHub web site</a>,
|
|
selecting your repository and clicking the <a href="gitdeveloper.shtml#pull">Pull
|
|
Request button</a>. For more info, see the <a href="gitdeveloper.shtml#pull">developer
|
|
instructions,</a>
|
|
</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h2 id="errors">Compiler Errors and Warnings</h2>
|
|
<p>As of 9/14/2025 roughly 2000 warnings were being reported by the Eclipse. You can ignore
|
|
these for now.</p>
|
|
|
|
<h2>JUnit Testing and Test Coverage</h2>
|
|
<p>If you wish to run the test coverage tool, you need to add this VM argument to the run
|
|
configuration:</p>
|
|
|
|
<div class="wide">
|
|
<code>-Djmri.shutdownmanager=jmri.util.MockShutDownManager</code>
|
|
</div>
|
|
|
|
<p>You also need to run Ant build.xml with the two targets "realclean" followed by "tests"
|
|
enabled. This configures the logger routines to log correctly during testing.</p>
|
|
|
|
<p>If you want to run a test coverage report accessing all of the tests in
|
|
sub-directories, you'll need to create a test class that will invoke all of the tests within
|
|
a directory and sub-directories. Below is an example that will run all of the tests in the
|
|
directory "jmri.jmrit.operations":</p>
|
|
<div class="wide">
|
|
<pre>
|
|
package apps.tests;
|
|
|
|
import org.junit.internal.TextListener;
|
|
import org.junit.platform.runner.JUnitPlatform;
|
|
import org.junit.platform.suite.api.ExcludeClassNamePatterns;
|
|
import org.junit.platform.suite.api.SelectPackages;
|
|
import org.junit.platform.suite.api.SuiteDisplayName;
|
|
import org.junit.runner.JUnitCore;
|
|
import org.junit.runner.Result;
|
|
import org.junit.runner.RunWith;
|
|
import org.junit.runner.notification.RunListener;
|
|
|
|
/**
|
|
* Invoke all the JMRI project JUnit tests via a GUI interface.
|
|
*
|
|
* This file is part of JMRI.
|
|
*
|
|
* JMRI is free software; you can redistribute it and/or modify it under the
|
|
* terms of version 2 of the GNU General Public License as published by the Free
|
|
* Software Foundation. See the "COPYING" file for a copy of this license.
|
|
*
|
|
* JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
* WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
|
|
* A PARTICULAR PURPOSE. See the GNU General Public License for more details.
|
|
*
|
|
* @author Bob Jacobsen
|
|
*/
|
|
@RunWith(JUnitPlatform.class)
|
|
@SuiteDisplayName("OperationTests")
|
|
@SelectPackages({"jmri.jmrit.operations"})
|
|
@ExcludeClassNamePatterns({"HeadLessTest","FileLineEndingsCheck","ArchitectureTest"})
|
|
public class JUnitOperationsTests {
|
|
|
|
static public void main(String[] args) {
|
|
run(JUnitOperationsTests.class);
|
|
}
|
|
|
|
/**
|
|
* Run tests with a default RunListener.
|
|
*
|
|
* @param testClass the class containing tests to run
|
|
*/
|
|
public static void run(Class<?> testClass){
|
|
run(new TextListener(System.out),testClass);
|
|
}
|
|
|
|
/**
|
|
* Run tests with a specified RunListener
|
|
*
|
|
* @param listener the listener for the tests
|
|
* @param testClass the class containing tests to run
|
|
*/
|
|
public static void run(RunListener listener, Class<?> testClass) {
|
|
JUnitCore runner = new JUnitCore();
|
|
runner.addListener(listener);
|
|
Result result = runner.run(testClass);
|
|
System.exit(result.wasSuccessful() ? 0 : 1);
|
|
}
|
|
}
|
|
</pre>
|
|
</div>
|
|
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|