Tools are a big part of being a productive developer on OpenJFX and we aim to provide excellent support for all three major IDEs: NetBeans, IntelliJ IDEA, and Eclipse. Regardless of which development environment you prefer, you should find it easy to get up and running with OpenJFX. We hope you will return the favor by submitting patches and bug reports!
This section assumes that you have already succeeded in Building OpenJFX. A gradle build must complete before IDE support will fully work (otherwise your IDE will just be a glorified text editor with lots of red squiggles!). Specific instructions for using each IDE is provided below, followed by a discussion on Developer Workflow, Using Mercurial, and Communication with other members of the team. Further information on how we work can be found under Code Style Rules.
IDE Pre-Requirements
Despite the fact that most of the major IDE's support gradle directly, we have decided to provide pre-generated IDE configuration files in order to make using an IDE smooth and painless. As the IDE's support for gradle improves, we may be able to update these instructions to rely on that support instead of the checked-in project files that we have today.
IMPORTANT: Ensure that you do not have gradle plugins for NetBeans or Eclipse (for Eclipse specific gradle configuration, see below) installed. They will conflict with the pre-generated IDE files. In the future, we may move to gradle builds within the IDE's as support becomes better.
Get a build of the latest JDK
You should use the latest OpenJDK when developing OpenJFX as OpenJFX continuously bumps the minimum JDK version. You can use the latest stable version or early access builds which can be found on http://jdk.java.net/12/ (replace the number for later versions). Starting from JDK11, JavaFX/OpenJFX is not included in the JDK anymore.
If you are building and running native libraries, you need to make sure you use the same version of JDK for NetBeans that you use to build JavaFX with gradle. In particular, if you try to mix a 32-bit JDK and a 64-bit JDK, the binaries will fail to load.
Get an IDE that supports the latest JDK
JDK9 brought modularization to the platform (including OpenJFX) and JDK10 brought Local-Variable Type Inference (AKA "var"). Later versions will bring more language changes. All these require IDE support, which means that you should always use the latest IDE versions, even early access builds. Not all IDEs will be able to advance equally in their support (some still have bugs with lambdas from JDK8), so keep in mind that there will be bugs. You are encouraged to work with your IDE's development team to resolve these.
NetBeans: https://netbeans.org/downloads/
IntelliJ: http://www.jetbrains.com/idea/download/
Eclipse: http://download.eclipse.org/eclipse/downloads/
Once you have downloaded and installed an IDE, you will need to configure it to the latest JDK version. This will be explained later on for each particular IDE. If you use an IDE without current support, OpenJFX will not compile and you will not be able to run from within the IDE.
JDK-8 Only: Delete jfxrt.jar (or move it to a different directory)
JavaFX is bundled with the JDK as an extension. The jfxrt.jar is located in the extension directory called 'ext' where Java is installed. You must remove it from this directory for the IDE's to work properly. The issue is this: If jfxrt.jar is in the extension directory, it will get seen before the code in your IDE. This means you won't be running or testing the code in your IDE. For more information on why this is a problem, see Unique Challenges of Working on the JDK.
By moving jfxrt.jar to a standard cache directory, your IDE can reference it to find binary versions of classes that are not yet open source. Further, when both jfxrt.jar and your IDE reference a class, the class from the IDE will be chosen.
IMPORTANT: Do not skip this step. If you do, you will not be running the code in your IDE and will waste hours wondering why you make changes and they don't run.
Using NetBeans (JDK-8)
Many commiters are using NetBeans to develop Java and native code. NetBeans projects have been configured for both. Native projects in NetBeans are currently not configured to build using either Make or gradle, however ant build works in NetBeans and will build the classes and jar files needed for the IDE.
- Edit netbeans.conf
- Invoke NetBeans
- Add the JDK8 Platform
- Import NetBeans projects
- Rebuild
- Run sample code
- Run sample code with grade built shared libraries
Invoke NetBeans
Note that before you invoke NetBeans, you may need to clear your old defaults and start with a fresh NetBeans install or you might get errors.
Add the JDK8 Platform
Invoke Tools->Java Platforms
NOTE: You must add a new platform named "JDK 1.8" even if you already have your default platform pointing to a JDK 8 platform.
Import the NetBeans Projects
Open Project... (you may need to resolve missing junit jars, don't open web or builders for now)
Rebuild
Select one of the projects to build (controls or web is a good choice depending on what you want to debug). This might take a long time depending on how fast your machine it. There should be no red marks on any of the projects.
Run Sample Code
Here is some sample code that was hooked up to use the base, graphics and controls projects. When saved, these projects were built by the IDE and the same code executed using the source in the IDE.
Run Sample Code with gradle built shared libraries
//TODO - explain how to hook up the shared libraries in the run dialog
Using IntelliJ IDEA
IntelliJ is a popular IDE that is used by many committers to develop JavaFX code. An IntelliJ project has been created for you that you need to open. The steps to use IntelliJ are:
Open the IntelliJ Project
Make
Run sample code
Run sample code with grade built shared libraries
Open the IntelliJ Project
IMPORTANT: Open IntelliJ on the 'rt' directory exactly as indicated in the image above.
Make
Build->Make Project
Run Sample Code
Run Sample Code with Gradle Built Shared Libraries
//TODO - explain how to hook up the shared libraries in the run dialog
Using Eclipse
Eclipse is a popular IDE that is used by many committers to develop Java code. Eclipse project files (.project
and .classpath
) have been created and checked into the repository. You should use the latest Eclipse version, or at least a version that supports JDK N-1 (for OpenJFX N) after patching (see below on patching).
OpenJFX is built using Gradle, which uses the javac compiler (even when run through Eclipse), and uses the Gradle wrapper to specify its current version. Various tasks, such as testing, are also configured through Gradle. However, you can still use Eclipse's compiler (ECJ) to take advantage of its speed as an incremental compiler, and of Eclipse's faster unit tests runner. Gradle is mandatory for the following phases:
- The initial setup (./
gradlew
or /.gradlew build
) that generates resources that are needed for the build. - Verify that the build task is successful with javac (because Eclipse's compiler can give different results sometimes).
- Running tests in the cases where Eclipse isn't configured to run them, or when the different compilers produce different results.
You can either use Gradle from the command line or through Buildship, which integrates Gradle into Eclipse.
Import the Eclipse Projects
You can either import the projects as Java projects and then run Gradle manually from a command line, or import them directly as Gradle projects with Buildship and use Gradle from within Eclipse. If you import as Java projects, you can later also import them as Gradle projects to add Buildship's functionality to them.
Importing as Java-only projects
To import as Java projects:
- Go to
File -> Import -> General -> Existing Projects into Workspace.
- Set the root directory to the base repository path.
- Check
Search for nested projects.
- Click
Finish
Importing as Gradle+Java projects
Use the latest Buildship version, as the Gradle version used in OpenJFX updates from time to time and Buildship needs to support that Gradle version. The Gradle Tasks view will list all the tasks that are configured in OpenJFX.
The project structure for Gradle is such that the root directory contains the parent project (called jfx
, or previously rt
) with all other projects being its children.
NOTE: this process will override the projects' Eclipse configuration files that come with the repository, and will cause them to not work anymore. This is because Gradle/Buildship does not know yet how to create the correct configuration files by itself. However, since we are using a git repository, we can revert the breaking changes. This will allow us to work with both Eclipse and Gradle/Buildship.
- Install Buildship.
- Go to
File -> Import -> Gradle -> Existing Gradle Projects.
- Set the root directory to the base repository path.
- If your workspace setting is to use the wrapper by default, there is no need to override the settings. Otherwise specify
Gradle wrapper
. Finish and wait for the workspace to rebuild. This will result in many compilation errors as described in the note above.
Revert all .classpath files (and clean and rebuild if it does not happen automatically - this will some take time). There should be no compilation errors.
What this process does is add the Gradle nature and build command to the .project files. This means that these files are now different than the ones in the repo. Additionally, the .settings folder for each project will contain a Buildship pref file. You will need to resolve the conflicts with the upstream repo.
Using EGit (TODO this section)
It's recommended that location of the local git repository not be inside the Eclipse workspace directory.
Configure Eclipse to use the latest JDK
- Go to
Window -> Preferences -> Java -> Installed JREs
andAdd -> Standard VM
and point to the latest version. If you want to find a regression or backport, you can switch to earlier versions underInstalled JREs
(will require rebuilding). You might see a warning that Eclipse does not support this Java version, this should not cause issues. - Go to
Window -> Preferences -> Java -> Compiler
and set the compiler compliance level to the latest. You might not have an option for an unreleased version of Java. For example, if compliance level 11 is not available, install the patch from the update site: http://download.eclipse.org/eclipse/updates/4.9-P-builds/. Similarly, for Java 13 use: https://download.eclipse.org/eclipse/updates/4.13-P-builds.
Building the workspace can take some time. However, thanks to Eclipse's incremental compiler, you do not need to rebuild all of it on every change.
NOTE: Dialog.java
in the controls module currently gives a compiler error because of a bug in Eclipse. It can be worked around be moving the erroneous line out of the lambda expression. Remember to ignore this change when working against a revision.
JUnit tests
Eclipse can run JUnit tests as an alternative to the Gradle tasks.
Right click on the resource you want to test (project/package/class) and select Run as -> JUnit Test
.
You might need to add the following VM arguments:
-Djava.library.path=<path to repo>/build/sdk/lib
-Djavafx.toolkit=test.com.sun.javafx.pgstub.StubToolkit
When running test.javafx.scene.web.WebViewT
est
, instead of the -Djavafx.toolkit
argument, use:
-Djava.library.path=<path to repo>/modules/javafx.graphics/build/module-lib:<path to repo>/modules/javafx.web/build/module-lib
Using working sets
Working sets allow you to group projects. The projects in OpenJFX contain its modules projects, like base and graphics, but also the apps and test projects. If you do not use these, you can create working sets for them and hide them.
Running a dependent project
Having an external project that uses the development OpenJFX modules is useful for debugging and testing.
Create a new Java project and add a module-info.java
that requires the needed modules. For example:
In the project properties, go to Java Build Path -> Modulepath
and add the required projects.
If when running you receive warnings about missing packages or modules, edit the run configuration by going to its Dependencies -> Override Dependencies
, then delete the launch dependencies and Override
.
If when running you receive an error like:
Graphics Device initialization failed for : d3d, sw Error initializing QuantumRenderer: no suitable pipeline found
Then add -Djava.library.path="<path to repo>\rt\modules\javafx.graphics\build\module-lib"
to the VM arguments in the launch configuration.
Run Sample Code (NOTE: old)
Run Sample Code with Gradle Built Shared Libraries (Note: old)
//TODO - explain how to hook up the shared libraries in the run dialog
//TODO - these are the VM Arguments: -Djava.library.path=${workspace_loc:rt}/build/mac-sdk/rt/lib