Opening Existing IntelliJ Projects

Jan 10, 2020


How to get existing IntelliJ projects to work when opening them on a new machine.

This example focuses on using Open JDK 11, Java FX 11, and IntelliJ Community 2019.3.

1. Install Software

You will need to install the following software:

  1. Java JDK 11: download and install from AdoptOpenJDK using the installer for your platform. Do NOT install from the Oracle site (for IP reasons).
  2. Java FX 11 Libraries: download from Open JFX and unzip to a known location where you want to store these libraries (e.g. /Users/javery/libs/javafx).
  3. IntelliJ 2019.3 Community. download and install from Jetbrains IntelliJ IDEA home page. Community is open source, and should suffice.

2. Setup your environment

I recommend setting up path variables for your JAVA and JFX installations. In my .zshrc I’ve added the following entries to track my installation directories and add the Java executables to my path (which enables java, jar etc. from the command-line).

export JAVA_HOME='/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home'
export JAVA_FX_HOME='/Users/javery/lib/javafx-sdk-11.0.2'
export PATH=$PATH:$JAVA_HOME/bin

This should work for any Unix shell (e.g. bash, zsh) in the appropriate config file. On Windows, you would want to add these as environment variables and update your path accordingly.

3. Setup IntelliJ

Out-of-the-box, IntelliJ won’t know about your Java 11 installation. To fix this:

  1. Launch IntelliJ, and from the Title Screen, click on Configure-Structure for New Projects.
  1. Under Platform-Settings, click on SDKs, then + and add a new Entry pointing to your Java 11 installation directory. Click OK to save it.

4. Open a project

Download and unzip this sample code, or a similar project that you want to work with.

Launch IntelliJ IDEA, and from the launch screen, select Open. Navigate to the top-level directory that contains the .iml file and open the directory (do NOT select any files, just the directory itself).

You will get a series of errors. We’ll walk through fixing each one in order.

Error 1: Unable to locate SDK

You may see a banner at the top of the window stating that “Project SDK not defined”. Click on “Setup SDK” beside the error (or File-Project Structure).

Select “Project” from the left-hand side, and set the Project SDK to the SDK you installed. Also set the language level to the same version (e.g. 11 for both).

Error 2: Missing Libraries

You will also see that IntelliJ “complains” about the code, by underlining what it considers to be errors.

Don’t panic! The problem is that IntelliJ doesn’t include the JavaFX libraries, and it doesn’t know where to find them. From the imports at the top of the java file, we can see that the code is referencing a number of JavaFX packages: javafx.application, javafx.scene and javafx.stage. These correspond to JAR files that are included in Java FX.

To set the location of these files based on where you installed Java FX:

  1. Click on File-Project Structure, then click on Libraries.
  2. Click + and add details for your JavaFX installation. It should look something like this. Click OK.

Now all of the libraries are available to the compiler, and the errors should disappear.

Error 3: Setting the “source root”

IntelliJ needs to know what to consider the top-level of your source directory (it may seem obvious with a simple project, but complex projects may have a complicated directory structure).

In the Explorer pane on the left, right-click on the “src” folder. Choose “Mark Directory As…” and select “Sources Root”. It should then be selectable and the Main class.

You should be able to build the project at this stage (Build-Build Project).

Error 4: Setting the Run Configuration

Running it is the last hurdle. If you run it (Run-Run from the menu), you will likely see an error like this:

Error: JavaFX runtime components are missing, and are required to run this application

To fix this, we need to modify the Run Configuration so that the Java Virtual Machine (JVM) can find the Java FX libraries at runtime.

  1. Click on Run-Edit Configurations. If you see an entry for HelloFX, go ahead and select it, otherwise click on the + sign and add a configuration for an Application. It should look like this:
  1. Add the following to the VM options, usingt the environment variable that we setup earlier to point to your JAVA_FX installation directory. Click OK when finished.

--module-path ${JAVA_FX_HOME}/lib --add-modules javafx.base,javafx.controls,javafx.fxml,javafx.graphics,javafx.media,javafx.web

  1. Click on the Run button (Run-Run from the menu) and it should launch.

Typically you would need to edit the Run configuration for each of your Java FX project file. You can also make this the default behaviour for any project that you run, so that the Java FX VM options are always used. To do this, click on Help-Edit Custom VM Options and add the VM options line (from above) to the bottom of the options list.