This section covers setting up a development environment for running, modifying and extending RCE on your local machine. After completing this section you should be able to build and run a development version of RCE from your local development environment.
The development environment is built on top of
OpenJDK 11 and
Eclipse for RCP and RAP Developers, Version 2022-03
Eclipse Checkstyle Plug-in
Make sure you have a Java Development Kit installed on your system in version 11 or higher. The canonical choice of JDK is Eclipse Temurin Version 11.
If you are installing a JDK on a centrally administrated computer that already has Java installed, it is usually a good idea to uncheck the "Install public JRE" option during installation.
Download and unpack "Eclipse for RCP and RAP Developers" in version "2022-03" from the Eclipse Foundation. In the following sections, this version is assumed.
OpenJDK 11 and Eclipse 2022-03 are most widespread among developers and provides a relatively stable basis for development. However, newer versions of both have been reported to work anecdotally.
Adapt the eclipse.ini file found in the base directory of
your Eclipse installation. The following changes are required for productive
development of RCE. For additional options, please refer to the Eclipse
documentation at https://wiki.eclipse.org/Eclipse.ini.
Set the proper path to your JDK installation by adapting the
-vm parameter: <your
path>/jdk11/bin immediately below the -vm
line.
Change the maximum heap size to at least 2 GiB by adapting the
-Xmx parameter somewhere below
-vmargs. Change this line to, e.g.
-Xmx2048m. Add such a line if it does not
exist.
Start Eclipse and install the "Eclipse Checkstyle Plug-in" via Help -> Eclipse Marketplace -> Checkstyle. Restart Eclipse if you are prompted.
If you already have other projects in your Eclipse workspace, it is recommended to create a new workspace for RCE. There are some necessary global settings that may interfere with the other projects (e.g. the so-called "target platform").
Disable "Project > Build Automatically" in the main menu to speed up the next steps.
In the eclipse preferences (avaible from "Window"-> "Preferences"), open the page "Plugin-Development" -> "DS Annotations" and check the box for "Generate descriptors for annotated sources." Set the descriptor directory to "OSGI-INF/generated".
There are currently three ways to properly import the complete RCE source code: from the SVN repository, from provided zip files, or from GitHub. At the moment, only the SVN approach provides access to the current development tree; for the time being, the zip files and the GitHub repository are only updated on release.
Option 1 - Importing from the RCE SVN repository, if you have access to it (as the repository is currently hosted internally at DLR):
Install Subclipse (or alternatively Subversive) if you don't already have an Eclipse SVN plugin installed. Note that when using Subclipse, you may have to switch to the "SvnKit" SVN interface in the "Team > SVN" preferences; this is normal.
Open the "SVN Repositories" view (Window > Show View > Other > SVN).
Add https://svn.dlr.de/rce/new/rce/trunk as
a new SVN repository location.
Expand the location entry and select all projects (the entries starting with "de.rcenvironment") inside of it.
Right-click the selected projects, select "Checkout" and confirm if necessary. You should now see a long list of projects in the "Package Explorer" on the left.
If the checkout was performed correctly, there should be a small "M" (for "Maven") on most projects' icons, and also a small "J" (for "Java") on most of them.
Option 2 - Importing from the zip files provided with each release:
Browse to the "source" sub-folder of a release's download
location, for example
https://updates-external.sc.dlr.de/rce/10.x/products/standard/releases/10.1.0/source/
for the 10.1.0 release. Download both zip files, "source" and
"additions"; the latter contains binary artifacts like the
Dakota and TiGLViewer executables.
Extract both archives into the same target directory. You should see a list of more than 200 sub-folders, all except one beginning with "de.rcenvironment".
In Eclipse, select "File > Import > General > Existing Projects into Workspace" and choose the directory that you unpacked the archives into. You should see a long list of projects, once again, all except one beginning with "de.rcenvironment". Select all projects confirm the import.
Make sure not to change the "Search for nested projects" option in the import dialog; it must not be selected/checked.
Option 3 - Importing from GitHub:
For successfully importing the RCE project, you need a Git client with LFS support.
Clone https://github.com/rcenvironment/rce into a
directory of your choice.
The clone settings of certain Git clients (e.g. TortoiseGit), have an "LFS" option. Make sure that this option is enabled before you clone.
Check out the master branch; by default, this points
to the source code of the latest release.
In Eclipse, select "File > Import > General > Existing Projects into Workspace" and choose the directory that you unpacked the archives into. You should see a long list of projects, once again, all except one beginning with "de.rcenvironment". Select all projects confirm the import.
Make sure not to change the "Search for nested projects" option in the import dialog; it must not be selected/checked.
After you have successfully imported the RCE projects using one of the above methods, the next step is to set the RCE target platform in your workspace. A target platform provides external artifacts like the Eclipse RCP framework and various libraries. To get started with RCE development, the easiest way is to use a precompiled target platform. For convenience, there is a Eclipse .target file inside the code base that always points at an appropriate precompiled target platform release. Follow these steps to apply it:
In the Project Explorer, navigate to the
de.rcenvironment/eclipse/tp/remote
folder.
Open the default_release_or_snapshot.target file
by double-clicking it.
Select the "Locations" list entry starting with
"https://updates-external.sc.dlr.de/" and click "Update".
After a while, the list entry's description should end with
something similar to "242 plugins available" (the exact number
may vary). Save the file if necessary.
Click "Set as target platform" in the top right corner. You can close the .target file after this.
If you previously changed the global Java compiler compliance level e.g. to 1.8 for previous RCE releases, it is recommended to revert this setting to default, or explicitly set it to 11. This setting can be accessed by opening "Window > Preferences" from the menu, and then navigating to the "Java > Compiler" tab. If you never actively changed this setting, no action is required.
Enable "Project > Build Automatically". Eclipse will start building all projects against the new target platform, which provides all required libraries and OSGi bundles.
At this point, most projects will have a red error marker. To fix this, open the "Problems" view ("Window > Show View > Problems"). You should see a lot of "Plugin execution not covered by lifecycle configuration" entries. Right-click one of them, select "Quick Fix" from the context menu, select "Discover new m2e connectors" and click "Finish". Eclipse should present one or more installation options with "Tycho" in their name. Confirm their installation and restart eclipse.
You only need to do this once per Eclipse installation.
After this, all RCE bundles should compile without errors (with the exceptions noted below), and you are ready to start developing. If this is not the case, try running "Project > Clean > Clean all projects" from the main menu.
On Linux platforms, there will be compilation errors in some Windows-only Excel and TiGLViewer bundles (5 and 3 projects, respectively). We don't have an elegant solution for this problem yet. You can simply close these projects to get rid of the errors, as they won't be loaded at runtime anyway.
Before proceeding to the more detailled settings, try running RCE from Eclipse to verify your setup.
There are several pre-defined launch configurations for RCE. To find them,
navigate to de.rcenvironment/eclipse/launch in the "Project
Explorer" on the left.
A good starting point is the "default" configuration. Right-click the "rce.default.launch" file and choose "Run As > rce.default.launch" from the context menu.
RCE should now start and prompt for an RCE workspace location. Confirm the default value or choose another empty folder.
The Workspace Mechanic project in its original form is not being maintained anymore, and the original project site is gone. However, it has been forked and is being continued by a new maintainer at this location. While this is not an "official" successor, it seems to be the de-facto location of this project now.
Workspace Mechanic (which can be installed via Eclipse Marketplace from this location) is an Eclipse plugin that automates common settings in local workspaces. For RCE, the most important settings are the Java code formatting rules and templates. Other settings are provided for convenience, like disabling the console output limit, or showing line numbers in the editor.
Configuring Workspace Mechanic consists of copying a set of "rule" files to a location where the plugin can find them. There are two options for this:
If you want to apply the rules to all Eclipse installations on your
machine, use the .eclipse/mechanic subfolder in your home
directory; by default, this is /home/.<user
id>/.eclipse/mechanic
To apply the rules to a single Eclipse installation only, use <eclipse installation
folder>/configuration/com.google.eclipse.mechanic/mechanic
Using your system's file browser, navigate to the folder of your choice.
Using any SVN tool, check out
https://svn.dlr.de/rce/new/meta/eclipse/mechanic/ into a
sub-folder called "checkout" within it. (Note that the actual name of the
sub-folder is not relevant; adapt if you like.) This sub-folder now contains common
rules on its top level, and optional or experimental rules in sub-folders. Copy all
common rules to the parent folder (the one you started in), and add any optional rules
that you want to apply as well. (TODO add and describe batch/shell files for this.)
These rule files will most likely be integrated into the main project at some point, making this extra checkout step unnecessary. Please note that these rule files are currently not available as part of the GitHub source code mirror or the released source zip files either, which makes them inaccessible unless you have access to the internal SVN server.
The next time you open a workspace, Workspace Mechanic should pick up these rule files and show a notice asking if it should apply them. See the plugin's web site for further information.
If you only plan to try out or modify RCE locally, you can safely skip this section. If you plan to commit your changes to the central code base, however, you need these settings to get your code accepted into the repository. Code that does not match the style guidelines will be refused on commit. The Checkstyle-CS plugin simplifies development by highlighting violations that need to be fixed.
To configure Checkstyle-CS for RCE:
Open the Checkstyle preferences (Window > Preferences > Checkstyle).
Click "New" on the right side. Enter "RCE" as the name of the configuration.
Choose "Project Relative Configuration", click "Browse" and choose
de.rcenvironment/checkstyle/checks.xml.
Click "Ok" in the main dialog. The list of configurations should now have three entries; select "RCE" and click "Set as Default" on the right side.
Close the preferences with "Apply and Close" and confirm the rebuild.
We are currently using version 6.19 of the Eclipse CheckStyle plugin within the development team. Using a newer version (e.g. 8.0) works as well, but you may see error markers for constructs that do not actually violate the RCE code guidelines. Versions > 8.0 do not work with current code guidelines. We will most likely adapt/migrate the CheckStyle settings in the near future.
To configure the Eclipse source code formatter:
Open the code formatter preferences (Window > Preferences > Java > Code Style > Formatter).
Click "Import", browse to your de.rcenvironment/eclipse/
checkout folder and choose the "eclipse-formatter.xml"
file.
You should now see "RCE" as the "Active Profile".
Click "Apply and Close" to activate the settings.
There are rare cases where these code formatter settings lead to source files that are not being accepted by our CheckStyle rules. These inconsistencies are being collected and tracked in issue #0005898, and will be fixed/addressed in a future update.
You can also build a standalone version of RCE from Eclipse using Maven 3.5.3.
There are several pre-defined build configurations for RCE. To find them,
navigate to de.rcenvironment/eclipse/build in the "Project
Explorer" on the left.
To run a .launch file, right-click on it and choose the single entry in the "Run As" submenu of the context menu that appears.
Be aware to configure the recommended Maven Runtime Environment in version 3.5.3. In Eclipse you can select for each .launch file a locally installed Maven Runtime via "Run > Run Configurations ...".
Building a standalone RCE installation (which is called a "product" in Eclipse RCP terms) generally consists of two steps: Providing a so-called "platform repository", and then building the actual product on top of it. There are two possible approaches for this:
Using the .launch files in the "using default remote
repository builds" sub-folder, it is possible to avoid
building your own platform repository, and fetch a pre-built one
from the main repository servers (currently hosted at DLR) instead.
One reason for this can be be to ensure that you are building
against the exact same platform repository as a certain RCE release.
Another reason is to simplify your local development setup if you
have no reason to customize the target platform setup (e.g. by
adding libraries).
The most flexible way to build RCE from source is to compile a
local platform repository yourself. This is simply done by
navigating to the "de.rcenvironment.platform/eclipse
folder (from the root of your workspace) and executing the single
.launch file that is located there. On the first run, the build
process may download quite a few resources from Maven Central;
subsequent runs should be fairly quick. Once the build has finished
(there should be a "SUCCESS" message near the bottom of the console
output), you can build the main product using the .launch files in
the "using local repository builds" sub-folder of the
previously mentioned location.
Regardless of whether you use a pre-build platform repository or compile one
locally, running the "RCE - build default product (snapshot, using
<...>) .launch file is the best way to produce a standard local
product build. The other .launch files are intended for more specific use
cases.
The main product build takes several minutes to complete. Once it has
finished, you will find the .zip files containing the final product in the
folder
de.rcenvironment/target/de.rcenvironment.modules.repository.mainProduct/products
(You may have to refresh the de.rcenvironment project in the Project Explorer to
see it.)
Building RCE completely from the command line is somewhat complicated as it is a multi-step process in which later steps must reference the output artifacts of previous steps. To simplify this, the command-line build will be further encapsulated by front-end scripts, which will then be documented here. In the meantime, please use the steps described above to trigger the build process from Eclipse.
Note that both the Eclipse-based and the command-line build trigger the same Maven steps in the background. Because of this, the build triggered from Eclipse produces the exact same artifacts as a command-line build (which is used in Continuous Integration and for releases).
TODO document the new command-line build when ready