Dependency upgrades
The Eclipse ESCET toolset has various dependencies. From time to time, these dependencies need to be upgraded. This page discusses for some of the major dependencies when to upgrade and how to upgrade:
Eclipse Platform/IDE upgrades
The Eclipse ESCET IDE is based on the Eclipse IDE, which in turn is based on the Eclipse Platform. The Eclipse IDE is also used as the development environment of choice for Eclipse ESCET development.
The Eclipse ESCET upgrade policy for the Eclipse Platform/IDE is:
-
Considering the overhead, only upgrade if there is a use for it. For instance, if we need a bug fix, some new feature, or so.
-
Upgrade to a new Eclipse version at least once a year, to stay current.
-
Consider the interplay between Eclipse and Java versions. Upgrading Eclipse may require upgrading Java if the new Eclipse version has a higher minimum Java version requirement. Upgrading Java may require upgrading Eclipse to a newer version that supports that Java version.
To upgrade to a new Eclipse Platform/IDE version:
-
Check out the information for the new version:
-
Check the Simultaneous Release overview page for the link between platform version (e.g. 4.20) and release name (e.g. 2021-06).
-
Check
https://www.eclipse.org/projects/project-plan.php?planurl=https://www.eclipse.org/eclipse/development/plans/eclipse_project_plan_N_NN.xmlwithN_NNreplaced by the platform version (e.g.4_20), for the project plan of the release, including detailed information about the supported target environments (operating systems, Java versions, etc). -
Check
https://www.eclipse.org/eclipse/development/readme_eclipse_N.NN.phpwithN.NNreplaced by the platform version (e.g.4.20), for the README of the release. -
Check the New & Noteworthy page for the new release and all intermediate releases since the previous version. Note that you can switch to the New & Noteworthy pages of previous releases using the dropdown at the bottom of the page.
-
-
Upgrade the development environment
-
Alternative 1: set up a fresh new development environment.
-
The benefit of this alternative is that you get a clean new environment, and can use it side-by-side with existing development environments. The downside is that you have to manually configure the new environment, or manually migrate your workspace and settings. You also have to cleanup or remove your old development environments, in case you don’t use them anymore.
-
Set up a new development environment for the new Eclipse IDE version.
-
-
Alternative 2: in-place upgrade of an existing development environment.
-
The benefit of this alternative is that you can keep your existing environment, preventing multiple such environments as well as manual migrations. The downside is that you run the risk of older things remaining in your development environment, requiring manual cleanup.
-
Update the P2 Director section of the Oomph setup (
org.eclipse.escet.setup), if needed. Especially, consider what is no longer compatible with the new Eclipse version and remove it, or replace it by an alternative. -
If you removed anything from the P2 Director section of the Oomph setup, also remove it manually from your development environment:
-
Click .
-
Click the Installation Details button.
-
Select on the Installed Software tab the item to remove and click the Uninstall… button.
-
On the Uninstall dialog, click the Finish button.
-
When asked to restart the Eclipse Platform, click Restart Now (newer Eclipse versions) or Yes (older Eclipse versions).
-
Repeat these steps for each item that was removed from the P2 Director section of the Oomph setup.
-
-
Update your installation profile for the new Eclipse version, and apply it:
-
From the toolbar, select the dropdown menu of the Open User item and choose Open Installation.
-
Select the Installation file:… node.
-
In the Properties view, change the Product Version to the Eclipse Platform edition of the new Eclipse version.
-
Save the
installation.setupfile. -
Click .
-
Once Eclipse restarts, you should see some initialization progress at the bottom right corner of the development environment window.
-
Wait for the Eclipse Update dialog to appear, indicating that The installation does not satisfy the requirements list below.
-
Click the Install button to update Eclipse.
-
Wait for the update to complete, while observing the progress at the bottom right corner of the development environment window.
-
If a Trust dialog appears, click Select All and then Trust Selected.
-
After some time, notice the Oomph icon with the flashing warning sign (
) at the bottom right corner of the development environment window. -
Click it to open the Eclipse Updater window.
-
Click Finish to restart Eclipse, completing the update.
-
Once Eclipse restarts, you may see a Older Workspace Version popup.
-
If so, click Continue to update your workspace to the new Eclipse version.
-
-
-
-
Version updates
-
Update the target platform (
org.eclipse.escet.releng.target/org.eclipse.escet.releng.target.target), configuring new versions for the Eclipse IDE and Orbit update sites. -
Update
dev-env-setup.asciidocto match the new Eclipse version. -
Update
org.eclipse.platformversion for the product feature (org.eclipse.escet.product.feature/feature.xml). -
Update Eclipse and Orbit update site URLs in the product (
org.eclipse.escet.product/escet.product). -
Update Maven plugin third party dependency versions to match the versions of these plugins from the target platform (
org.eclipse.escet.common.asciidoc/pom.xml). -
Commit any changes.
-
-
Update target platform and adapt to the new Eclipse version
-
Let Oomph reactivate the target platform, and address any issues.
-
Commit any changes.
-
Force a rebuild in Eclipse ().
-
Check the workspace for any errors/warnings and address them if any.
-
Commit any changes.
-
Check New and Noteworthy (release notes) of the new Eclipse version and relevant intermediate versions for changes and adapt as necessary.
-
Commit any changes.
-
-
Java formatter profile
-
Right click the
org.eclipse.escet.common.javaproject in the Package Explorer view and choose Properties. -
In the properties dialog, select .
-
Make sure the Unmanaged profile is selected and click Edit….
-
Change the Profile name to
tmp. -
Click OK to close the profile editing dialog, and then clicking Apply and Close to close the properties dialog.
-
Remove the tmp profile:
-
Remove the
formatter_profile=_tmpline from the.settings/org.eclipse.jdt.ui.prefsfile in the project. -
Navigate to .
-
In the dialog, navigate to .
-
Select the tmp profile.
-
Click the Remove button and confirm the removal by clicking Yes.
-
Close the preference dialog by clicking Apply and Close.
-
If an Oomph preference recorder dialog appears, dismiss it by clicking Cancel.
-
-
If in the
org.eclipse.escet.common.javaproject, in the.settingsdirectory, there are changes to any of the*.prefsfiles:-
Run
./copy_here.bash ../../common/org.eclipse.escet.common.javafrommisc/java-code-styleto copy the new preferences to the central place. -
Run
./copy_there.bashfrommisc/java-code-styleto copy the new preferences to all relevant projects. -
Refresh all projects, and wait until the rebuild completes.
-
Commit the preference changes.
-
Reformat all projects.
-
Commit any code changes.
-
-
In case of new formatter preferences, configure them as desired. Apply each preference change separately, to allow easier reviewing:
-
Change a single formatter preference on the
org.eclipse.escet.common.javaproject. This requires giving the unmanaged profile the name tmp again, as before. -
Remove the tmp profile, as before.
-
Run
./copy_here.bash ../../common/org.eclipse.escet.common.javafrommisc/java-code-styleto copy the changed formatter preference to the central place. -
Run
./copy_there.bashfrommisc/java-code-styleto copy the changed formatter preference to all relevant projects. -
Refresh all projects, and wait until the rebuild completes.
-
Commit the preference changes.
-
Reformat all projects.
-
Commit reformatting changes.
-
-
If any changes were made to the formatter preferences, manually update the
org.eclipse.escet.*.metamodelprojects to have the same formatter settings as the rest of the projects.
-
-
Java errors/warnings settings
-
Right click the
org.eclipse.escet.common.javaproject in the Package Explorer view and choose Properties. -
In the properties dialog, select .
-
Make a dummy change and apply it by clicking Apply and Close.
-
Click Yes when asked to Rebuild the project now to apply the changes of the Error/Warning settings?.
-
Revert the dummy change, using again the same steps.
-
In case of changes to
*.prefsfiles in the.settingsdirectory of that project, configure the new preferences as desired. -
Run
./copy_here.bash ../../common/org.eclipse.escet.common.javafrommisc/java-code-styleto copy the new preferences to the central place. -
Run
./copy_there.bashfrommisc/java-code-styleto copy the new preferences to all relevant projects. -
Manually update the
org.eclipse.escet.*.metamodelprojects to have similar error/warnings settings as the rest of the projects (be aware, some settings are configured differently). -
Force a rebuild in Eclipse () and check for any warnings/errors, addressing them if any.
-
-
Eclipse application launch configurations
-
Select each Eclipse application launch configuration in the Run Configurations dialog, then select the next one, and so on. In the Run Configurations dialog, these launch configurations are under the Eclipse Applications category.
-
Run each Eclipse application launch configuration, from the Run Configurations dialog. Make sure they work as expected.
-
If Eclipse makes any changes to the corresponding
*.launchfiles for these launch configurations, commit the changes.
-
-
Update Maven version
-
Check the embedded Maven version, by navigating to , selecting the build launch configuration under Maven Build, and observing the Maven Runtime version.
-
Ensure the Maven version in
Jenkinsfilematches the embedded Maven version. -
Ensure the Maven version in
misc/license-check-dependencies/Jenkinsfilematches the embedded Maven version. -
Update version of the
maven-plugin-apito match new Maven version (org.eclipse.escet.common.asciidoc/pom.xml). -
Update version of the
maven-plugin-annotationsif needed (org.eclipse.escet.common.asciidoc/pom.xml). -
Update version of the
maven-plugin-pluginif needed (org.eclipse.escet.releng.configuration/pom.xml).
-
-
Validation
-
Run a Maven build.
-
Ensure no errors or warnings during Maven build.
-
-
Dependency information
-
Run
misc/license-check-dependencies/license-check-dependencies.shand updateDEPENDENCIES.txtaccording to the output. -
Run
misc/license-check-dependencies/license-check-dependencies.shagain, to ensureDEPENDENCIES.txtis up-to-date.
-
Tycho upgrades
Eclipse Tycho is used for the Eclipse ESCET build.
The Eclipse ESCET upgrade policy for Tycho is:
-
Typically upgrading to a newer version can be done at any time, if it is considered relevant.
To upgrade to a new Tycho version:
-
Update
versioninorg.eclipse.escet.root/.mvn/extensions.xml. -
Update
tycho.versioninorg.eclipse.escet.releng.configuration/pom.xml. -
Update
maven.minimal.versioninorg.eclipse.escet.releng.configuration/pom.xml, if the new Tycho version requires a higher Maven version. -
Check Tycho release notes for changes and adapt as necessary.
-
Run a Maven build.
-
Perform a license check (
misc/license-check-dependencies/license-check-dependencies.sh). -
Ensure no errors or warnings during Maven build.
Java upgrades
Most of the Eclipse ESCET source code is written in Java.
The Eclipse ESCET upgrade policy for Java is:
-
Considering the overhead, only upgrade if there is a use for it. For instance, if we need a bug fix, some new feature, or so.
-
Upgrade when a Java version we use is no longer actively supported.
-
Only upgrade to a Java LTS release.
-
Don’t upgrade to newer Java versions immediately, but only after (industrial) adoption is high enough. As a general guideline, if at least 50% of developers, users and enterprises use the new LTS version, consider upgrading. Java usage is regularly surveyed, and reports can typically be found online. For instance, the 2021 Jakarta EE Developer Survey Report of the Eclipse Jakarta EE project indicates that in 2021 about 58% of the developers and 11% of the enterprises used Java 11.
-
Consider the interplay between Java and Eclipse versions. Upgrading Java may require upgrading Eclipse to a newer version that supports that Java version. Upgrading Eclipse may require upgrading Java if the new Eclipse version has a higher minimum Java version requirement.
To upgrade to a new Java version:
-
For major Java versions (e.g. 17 to 18):
-
Update all (plugin) projects:
-
Update
Bundle-RequiredExecutionEnvironmentfor all plug-in manifests. -
Update
JRE_CONTAINERin all.classpathfiles. -
Update
JRE_CONTAINERin all launch configurations (.launchfiles). -
Update Java versions in all
org.eclipse.jdt.core.prefsfiles (compiler.codegen.targetPlatform,compiler.compliance, andcompiler.source).
-
-
Update all metamodel projects (
org.eclipse.escet.*.metamodelprojects):-
Update the
autofix.pyscripts of these projects, by changing the compliance level resulting from replacements. -
Change in all
*.genmodelfiles thecomplianceLevel. -
Regenerate the model code for each metamodel project, by opening the corresponding
.genmodelfile, right clicking the root node of the opened generator model, and choosing Generate Model Code. There won’t always be changes.
-
-
Update the product:
-
Update
osgi.requiredJavaVersionin the product (org.eclipse.escet.product/escet.product). -
Update
osgi.requiredJavaVersionin the product launch configuration (org.eclipse.escet.product/*.launch).
-
-
Update the build:
-
Update Java version for
escet.java.versioninorg.eclipse.escet.releng.configuration/pom.xml. -
Update Java version for
executionEnvironmentinorg.eclipse.escet.releng.configuration/pom.xml. -
Update Java version in
Jenkinsfile. -
Update Java version in
misc/license-check-dependencies/Jenkinsfile.
-
-
Update all Java code and documentation:
-
Update Java keywords for
org.eclipse.escet.common.java.JavaCodeUtils.JAVA_IDS. Update the keywords themselves and the field’s JavaDoc, including the link to the Java Language Specification (JLS). -
Update
dev-env-setup.asciidocto match new Java version. -
Update links to specific versions of the Java documentation (search for
https://docs.oracle.com).
-
-
Search for the current Java version to find other references (e.g., search for
17).
-
-
For any Java versions (e.g. 17 to 18, or 17.0.1 to 17.0.2):
-
Update the JustJ update site URL in the target platform (
org.eclipse.escet.releng.target/org.eclipse.escet.releng.target.target). -
Re-activate the target platform using Oomph.
-
Update JustJ version for the product feature (
org.eclipse.escet.product.feature/feature.xml). -
Force a rebuild in Eclipse () and check for any warnings/errors, addressing them if any.
-
Run a Maven build.
-
Ensure no errors or warnings during Maven build.
-
Run
misc/license-check-dependencies/license-check-dependencies.shand updateDEPENDENCIES.txtaccording to the output. -
Run
misc/license-check-dependencies/license-check-dependencies.shto ensureDEPENDENCIES.txtis up-to-date.
-