Development Environment - mars-sim/mars-sim Wiki
Revised : 25 Sep 2021
In order to test, compile and code for mars-sim, you will need to set up a development environment by obtaining the following software and installing them on your machine at the minimum :
(1). JDK Requirement
Beginning r4945 (see comments), our master branch has officially been switched to using Java 11. We no longer support Java versions prior to 11.
As of r4268, our master branch has officially been switched to using jdk 9 or above (incompatible with jdk 8 from now on) as agreed upon in issue 37. Find your desired jdk package (Java 9 and above) and install it in your machine.
A. Install a Compiled Java 11 or OpenJDK 11 available at :
- Official OpenJDK
- Oracle's Official Java SE
- Oracle's RI Binary Java SE 17
- BellSoft's Liberica OpenJDK
- AdoptOpenJDK OpenJDK
- ojdkbuild's OpenJDK maintenance builds 8/11/15
- Zulu's OpenJDK 6/7/8/11/13/15/16/17
- SkyLandTW's OpenJFX 8
- alexkasko's older builds OpenJDK 6/7
- Amazon Corretto OpenJDK 8/11/16
Note 1 : Before Java 11, Oracle's Official JDK is bundled with JavaFX. Beginning Java 11, JavaFX is decoupled from JDK and is available separately.
Note 2 : OpenJFX is the open source version of the JavaFX API. Since the beginning of OpenJDK 8, OpenJFX has always been a separate package from OpenJDK.
Note 3 : There are some minor differences between Oracle's official JavaFX and OpenJFX, namely the video codec and webstart/browser,
Note 4 : Some linux distributions have already "openjfx" package ready for installation. Be sure to do a search for instructions on whether a particular version of OpenJFX is available on your linux machine. e.g. Ubuntu 15's openjfx; Debian's openjfx
B. Build your own Java 11 binary :
- OpenJDK Wiki on Building OpenJFX binaries
- OpenJDK Community Builds wiki
- David M. Lloyd's automated compilations of various OpenJDK branches
- SkyLandTW's detailed instructions on building OpenJFX based on Zulu's OpenJDK binary
- IcedTea's wiki
C. Manage your Java environment
If you have multiple versions of JDK/JRE installed, make sure you know which version you have designated to run on Eclipse IDE and make sure the path have set up properly to run from the same version by using "java -version" in the Command Prompt in Windows.
If your platform is Linux/MacOS, you may use jenv to simplify switching between Java 8, 9, 10 and 11.
Note that most Java apps are compiled under Java 8 and can only run on Java 8.
If you are on Windows OS, you may use the Oracle
Java Control Panel (Note : it came with Oracle Official JDK) to switch between various versions of Java.
Desktop Settings tab and choose the one you want. However, it doesn't always work, especially if you or an Java app that you have installed have already manually inserted a
JAVA_HOME variable in your system path.
In that case, you can always go to
Environment Variables panel to manually alter the
Path variable in such a way that you decide whichever Java version will be run. Note that the order of precedence is paramount.
D. Workaround for mars-sim binaries requiring OpenJFX (EXPERIMENTAL)
For making it possible to run the simulation from an IDE under JDK11 and OpenJFX, you need to add the following options to the JVM command line:
--module-path <path-to-jfx>\javafx-sdk-11\lib\ --add-modules=ALL-MODULE-PATH --add-opens javafx.base/com.sun.javafx.runtime=ALL-UNNAMED --add-opens javafx.controls/com.sun.javafx.scene.control.behavior=ALL-UNNAMED --add-opens javafx.controls/com.sun.javafx.scene.control=ALL-UNNAMED --add-opens javafx.base/com.sun.javafx.binding=ALL-UNNAMED --add-opens javafx.base/com.sun.javafx.event=ALL-UNNAMED --add-opens javafx.graphics/com.sun.javafx.stage=ALL-UNNAMED
--module-path should point to the installation directory of OpenJFX. The
--add-modules=ALL-MODULE-PATH is a very broad option, this can be reduced to specific module dependencies later. With
--add-opens module/package=ALL-UNNAMED, packages within modules can be made accessible for unnamed modules, in this case, the compiled classes of mars-sim. The current set of exceptions to the JDK11 access control system should get reduced with updated versions of the libraries that are currently not supporting java modules.
(2). Package Management Tool
Maven has been adopted as mars-sim's default build tool a few years ago because it's handy for running junit tests, handling dependencies, creating .class files and generating the jars.
However, running Maven under Eclipse IDE can be memory intensive and somewhat cumbersome.
Note 1: you do NOT need to install Maven separately in your machine if you use Eclipse IDE. Eclipse plug-in m2e will suffice.
The good news is that, beginning version 4.7, Eclipse IDE for Java Developers come with Maven Plugin for Eclipse pre-installed.
Depending on our need, we may switch to Gradle in future if Maven is inadequate.
See the GuiGarage's comments on Maven versus Gradle.
Also, see this blog regarding Maven Plug-in.
As of 3.1.0-p6, the official repository for mars-sim has been switched from SVN on Sourceforge to Git on GitHub.
As a result, the latest source code is hosted in the
Master Branch in GitHub Project Site and one may download the recent official releases and latest builds from the Release Tab.
All the official release versions would continue to be hosted at Sourceforge.
(4). IDE Tool
A. Console/Terminal/Command Line
- [Setting Up Command Line Environment with Git](/mars-sim/mars-sim/wiki/Setting Up Command Line Environment with Git)
- [Setting Up Command Line Environment with SVN](/mars-sim/mars-sim/wiki/Setting Up Command Line Environment with SVN)
B. Eclipse IDE for Java (Updated 6 Jul 2021 regarding Kotlin plug-in)
- [Setting Up Eclipse IDE with Git](/mars-sim/mars-sim/wiki/Setting Up Eclipse IDE with Git)
- [Setting Up Eclipse IDE with SVN](/mars-sim/mars-sim/wiki/Setting Up Eclipse IDE with SVN)
If you are running Windows 10, add Eclipse IDE's root folder to the exclusion list of the Windows Defender to speed up the startup of Eclipse. See this email.
NOTE 1 : As of build 6193, Eclipse Java IDE's latest version 2021-09 (4.21.0) is known to work well for developing mars-sim.
NOTE 2 : With Java 9 support, a library or a container can now be added to the module path as opposed to the classpath. see Eclipse Project Oxygen.1a (4.7.1a) - New and Noteworthy.
NOTE 3 : If you have multiple versions of JDK installed in your machine, make sure you have the following setup correctly : (1). Match the Java Compiler with your desire version (such as 11) at Menu's
Window | Preferences | Java | Compiler | Compiler compliance level : 11; (2). Match the
JRE System Libraryto
JavaSE-11. Double check it in
Java Build Path|
NOTE 4 : in order to avoid reporting minor changes due to # of adding/subtracting white spaces in Eclipse. Check the box "Ignore white space" at Menu's
Window | Preferences | General | Compare/Patchso that Eclipse may ignore line-endings and white space changes.
As of r4055, IntelliJ 2021.1.2 has been verified to work well.
- Download and install groovy SDK in your machine (IntelliJ's Groovy Plug-in may or may not work).
Note : Go to this site to download Apache Groovy and install it in your machine. Version 3.0.8 has been known to work well under IntelliJ.
- Associate each maven sub-module with Groovy's installed folder. This step is required for mars-sim's sub-module to work since IntelliJ IDE's Groovy plug-in does not automatically integrate with mars-sim. Note that Groovy is NOT required in case of Eclipse IDE.
Note : Go to this page in IntelliJ site and follow the steps in Add Groovy support for an existing project.
Associate your favorite JDK to all the modules of mars-sim by right clicking a sub-module and choose
Open Module Settings
To launch mars-sim with IntelliJ, in "Edit or Run/Debug Configurations", set up the following :
- Build and run :
Java Bundledor your favorite JDK,
- Main class :
- Program Argument :
- Working directory:
- Use classpath of module :
- If you use Java 16, make sure you update Kotlin to 1.5 or else mars-sim won't compile.
D. Netbean IDE
One must first experiment in setting up how to launch mars-sim from within Netbean.
Note : in all cases, the url for the current GH's repo is
https://github.com/mars-sim/mars-sim.git. The old SF's SVN repo at https://svn.code.sf.net/p/mars-sim/code will be closed soon. Please switch to GH's repo asap.
(5). Coding Guideline
We are in the process of developing a coding guideline. See [Coding Recommendations](/mars-sim/mars-sim/wiki/Coding Recommendations).