Eclipse IDE installation

Download and Install JavaFX

JavaFX is a set of GUI libraries that are required by a desktop application to show a graphical GEF-based editor and various charts (line chart, gantt chart, bar chart). A desktop application created by the Desktop Application Wizard will need JavaFX both at compile time and at runtime.

In this section, JavaFX 21.0.2 will be installed. You can also use a newer version with the same major number (e.g. 21.0.4), it should work without any issue.

  1. Go to the JavaFX download page: https://jdk.java.net/javafx21/

  2. Download the archive with JavaFX. E.g., if you are using Windows, click the 'zip' link next to the 'Windows/x64' label. As of December 2024, the current JavaFX version available at this web page is '21.0.2'.

  3. Install JavaFX. E.g., if you are using Windows, unpack the downloaded file to the 'C:\Program Files\Java' folder - a new folder 'C:\Program Files\Java\javafx-sdk-21.0.2\' should appear.

Download and install Eclipse Modeling Tools

  1. Download the ZIP archive with Eclipse 2024-09 from the Eclipse Modeling Tools 2024-09 web page

  2. Unpack the ZIP archive to a folder on your local drive.

  3. Start Eclipse (e.g. launch 'eclipse.exe' if you are using Windows).

  4. Open 'Help' → 'Eclipse Marketplace…​' and Install 'e(fx)clipse'. Do not restart Eclipse upon request, since there are some more installations to do.

  5. Install 'Desktop Application Wizard':

    1. Open 'Help' → 'Install New Software…​';

    2. Use https://nexus.am-sim.com/repository/amalgama-platform-p2/latest/ url in the Work with field;

    3. Install the 'Amalgama Tools'/'Desktop Application Wizard' feature.

    4. Restart Eclipse.

Set up JavaFX libraries path in Eclipse Workspace

Now that you have downloaded and installed Eclipse, the path to locally installed JavaFX libraries needs to be specified. This is essential for a successful compilation of the desktop applications in Eclipse - JavaFX is needed at compile time just as much as at runtime.

Note that this Workspace setup step must be done once for every new Workspace that you create in Eclipse. As soon as you create another Workspace, it will not pick the JavaFX path settings from any previous Workspace.

Do the following:

  1. Open "Windows" → "Preferences" dialog.

  2. Find "JavaFX" item (in the left menu).

  3. Fill in the "JavaFX 11+ SDK" field to contain the full path to the directory with JavaFX libraries (jar-files), see details below.

  4. Press 'Apply and Close'.

JavaFX preference

Use the full path to the 'lib' folder in your local JavaFX installation, for example:

C:\Program Files\Java\javafx-sdk-21.0.2\lib

Make JavaFX available at runtime

JavaFX should be available at runtime. The product file has a special parameter that defines the path to the JavaFX libraries:

  1. Find the "product" file of your project, open it in Eclipse.

  2. Go to the "Launching" tab.

  3. In the "Launching Arguments" section, open the tab with the OS type you are using.

  4. In the "VM Arguments" text field, see the value of the "-Defxclipse.java-modules.dir" parameter - this should point to the location of JavaFX libraries (the lib subfolder in the local JavaFX installation folder).

There are several ways to set this parameter.

Option 1: Use JAVAFX_HOME Environment Variable

The JAVAFX_HOME environment variable can be used in product files to enable the desktop application to use JavaFX libraries at runtime.

Add a new environment variable named JAVAFX_HOME, set its value to the full path of the local JavaFX folder (e.g., C:\Program Files\Java\javafx-sdk-21.0.2\). Note that this setup should be done only once.

In the product file, the "-Defxclipse.java-modules.dir" should be set to:

-Defxclipse.java-modules.dir="${env_var:JAVAFX_HOME}/lib"

The advantages of JAVAFX_HOME set globally are:

  • This env var setup should be done only once (but at each team member’s computer).

  • The product file does not contain any fixed paths to JavaFX, so each team member may have a different path to their local JavaFX installation.

However, security policies may prevent users from changing or setting environment variables. If that is your case, see the following options.

Option 2: Use String Substitution

In Eclipse, open Window → Preferences dialog, go to 'Run/Debug' → 'String Substitition' section. In the table, add a new substitution:

  • Name: JAVAFX_HOME

  • Value: full path of the local JavaFX folder (e.g., C:\Program Files\Java\javafx-sdk-21.0.2\)

This should be done for each new Eclipse workspace.

In the product file, the "-Defxclipse.java-modules.dir" should be changed to:

-Defxclipse.java-modules.dir="${JAVAFX_HOME}/lib"

Each team member should add the substitution into their Eclipse settings. As in the previous option, each team member may have their local JavaFX installation folder different.

Option 3: Put the Full Path to JavaFX into the 'product' File

You can also add the path to your local JavaFX installation directly into the product file.

In the product file, the "-Defxclipse.java-modules.dir" should be changed to:

-Defxclipse.java-modules.dir="C:\Program Files\Java\javafx-sdk-21.0.2\lib"

Note that your local JavaFX path may be different, change the parameter value accordingly.

That way, you make the 'product' file specific to your computer: it may not work correctly on other computers that use a different path to the local JavaFX folder. For that reason, setting local JavaFX libraries path directly in '.product' files should only be used for debugging purposes or in cases when it is not possible, for some reason, to set up the JAVAFX_HOME env variable (e.g., env variable modification is not available due to some security policies). Avoid placing the "product" with direct JavaFX path into the version control system unless you are the only person working on the project.

Troubleshooting JavaFX

Check This First

In this section, we refer to the folder where you have JavaFX installed as the full path to your local JavaFX installation.

This full path may look as follows (Windows example):

C:\Program Files\Java\javafx-sdk-21.0.2\

Please check that you have JavaFX installed locally: do you have access to the contents of the JavaFX installation folder in the File Explorer?

JavaFX compilation errors

If you have set up the JavaFX path in Eclipse (Window - Preferences - JavaFX - JavaFX 11+ SDK field) but still experience FX-related compilation errors, try removing all opened projects from Eclipse and importing them again.

JavaFX Availability at Runtime (JavaFX NoClassDefFoundError)

You may also face runtime errors similar to this one:

JavaFX NoClassDefFoundError error

The "java.lang.NoClassDefFoundError: javafx/embed/swt/FXCanvas" errors indicate that JavaFX libraries are missing in runtime.

  1. If you have set the JAVAFX_HOME env var - check its contents. It should contain the full path to your local JavaFX installation. Can this folder be read by the current OS user? Is the path correct?

  2. Try setting the JavaFX path directly in the 'product' file - see the Put the Full Path to JavaFX into the 'product' File section.

Enable Importing Maven Project into Eclipse

If you plan to work with Maven projects (e.g. with a console applications):

  1. Select Help → Eclipse Marketplace.

  2. Find 'Eclipse m2e - Maven support in Eclipse IDE Latest', click 'Install'.

  3. In the 'Confirm selected features' window, choose to install only the 'M2E - Maven Integration for Eclipse' feature (marked as 'required').

  4. Confirm Eclipse restart.

After restarting, your Eclipse is ready to import Maven projects.