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 zip files provided with each release:
Browse to the "source" sub-folder of a release's download
location, for example
https://download.rcenvironment.de/rce/10.x/products/standard/releases/10.6.0/source/
for the 10.6.0 release. Download the "source" zip file.
Extract the archive. 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 2 - Importing from GitHub:
For successfully importing the RCE project, you need a Git client with LFS support.
Clone https://github.com/rcenvironment/rce-main 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 an appropriate branch (e.g. main or integration10) or tag; by default, the main branch 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
folder.
Open the local_or_unpacked_thirdparty_build.target file
by double-clicking it.
Click "Set as active 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 C:\Users\.<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.
RCE's build system has undergone significant changes for the 10.6.0 release. Starting with that release, builds are always performed by using Bash scripts located in the "build" folder in the root of the repository. Building on Windows is still fully supported by calling these scripts within a "git bash" shell provided by the commonly used "Git for Windows" software package. Using these build scripts always generates builds for both Linux and Windows, regardless of the platform the scripts are run on.
For an introduction on how to execute the default ("product") build, refer to the
build/README.ad file in the rce-main repository. Note that
you will need to provide a matching build of the rce-thirdparty repository
to build against. You typically do not need to build that repository locally, as builds
matching each RCE release are conveniently available from the RCE download page. See the
de.rcenvironment/eclipse/tp/README.ad file for more information.
Note that the transition to the new build system is not fully complete yet, so you may still find traces of the old setup in the repository and in the documentation. Also, while this documentation enables you to build fully functional distribution packages of RCE, equivalent to the official zip release files, its is currently not describing all features of the new build system.