Building and Running OpenJFX
JFX consists of a forest of mercurial repositories. These repositories contain NetBeans, Eclipse and IntelliJ projects with the Java source, native projects and the scripts needed to build JavaFX components. A JavaFX component is a large and obvious unit of functionality, such as the user interface controls or the embedded web browser.
As you can imagine, building a UI toolkit for many different platforms is quite complex. It requires platform specific tools such as C compilers as well as portable tools like ant. The build and project structure of JavaFX like most large projects has evolved over time and is constantly being revised.
Building OpenJFX requires that you have the binary porition of OpenJFX. As of JDK7, JavaFX is co-bundled with Java so you will need the version of Java that matches the mercurial repositories you cloned. The rest of this document assumes that you are developing against JavaFX 8 (co-bundled with JDK8) and uses paths and naming accordingly.
Working with OpenJFX and JavaFX
Over the course of time, various components, projects and build structures will be contributed to OpenJFX until all of JavaFX is open source. In the meantime, you will need to download the JavaFX binary that matches OpenJFX for your platform and place your compiled code first on the class path. First though, you will need to download and install the tools needed to build OpenJFX and place them on your the command line path for your operating system.
Here are the tools required to build OpenJFX:
- JDK1.8 Snapshot release
- Ant 1.8.2
- Mercurial 1.8.2
- Cygwin (for Linux commands on Windows)
You will need to ensure that the command path is set up correctly. The java and javac commands should come from the JDK8 bundle by preference (current build minimum is JDK7). On some Linux systems, OpenJDK6 may be the system default. Use the '-version' switch to check each of java, javac and ant to verify the versions in your path, for example
# ant -version
Apache Ant(TM) version 1.8.2 compiled on December 3 2011
Here is the recipe for building OpenJFX (use a Cygwin shell on Windows):
- mkdir -p ~/open-jfx
- cd ~/open-jfx
- hg clone http://hg.openjdk.java.net/openjfx/8/master
- cd master
- mkdir -p artifacts/sdk/rt/lib/ext
- cp <PATH TO JDK>jre/lib/ext/jfxrt.jar artifacts/sdk/rt/lib/ext
- hg clone http://hg.openjdk.java.net/openjfx/8/master/rt
- cd rt
- Edit build-defs.xml (comment out '<propertycopy name="javac.debuglevel" from="${ant.project.name}.javac.debuglevel" silent="true" override="true"/>' if not already commented)
- ant
Note: JDK1.8 and the JFX contained within are are moving target, so you may need to refresh your snapshot periodically to match the items you are building.
In addition, the following files need to be downloaded and placed in "open-jfx/lib":
- antlr-3.1.3.jar
- antlr-runtime-3.1.3.jar
- stringtemplate-3.2.jar
Certain parts of JFX, e.g. JavaFX/SWT classes in rt/javafx-embed-swt, depend on SWT being available at compile time. Environmental variable SWT_DIR or ant property swt.path can be used to specify a directory with swt.jar. If neither SWT_DIR nor swt.path are specified, no classes that depend on SWT are built. TODO: does it make sense to look for swt.jar in open-jfx/lib as well?
Here is the command line needed to run OpenJFX (using the controls jar from OpenJFX):
- java -Xbootclasspath/a:<PATH TO HOME DIR>/open-jfx/master/rt/javafx-ui-controls/dist/javafx-ui-controls.jar:<PATH TO JDK>/rt/lib/jfxrt.jar" test.HelloButton
The above command assumes that you have a class test.HelloButton and that your OpenJFX directory is /Users/someone/open-jfx. If you have multiple versions of java installed on your machine, make sure you use the java that matches jfxrt.jar.
Setting Up Your System For Native Compilation
Configuring your system to be able to build native code is a bit of a black art. Hopefully we will have captured here steps that are both correct and comprehensive, but it has been our experience that lots of little things don't get documented than could trip you up (especially on Windows).
Linux Configuration
Setting up a linux build configuration is fairly straightforward. These build instructions were used for the "official" build platform of Ubuntu 10.04, but also on the latest Ubuntu 12.10. First, run the following command to install all the required development packages:
sudo apt-get update sudo apt-get install bison flex gperf libasound2-dev libgl1-mesa-dev \ libgstreamer0.10-dev libgstreamer-plugins-base0.10-dev libjpeg-dev \ libpng-dev libx11-dev libxml2-dev libxslt1-dev libxt-dev \ libxxf86vm-dev pkg-config qt4-qmake x11proto-core-dev \ x11proto-xf86vidmode-dev libavcodec-dev mercurial libgtk2.0-dev \ ksh libxtst-dev libudev-dev
Mac Configuration
To configure your Mac, make sure you have at least version 10.7 installed. Install the latest version of Xcode. Install the latest JDK 8 build. At present that should be sufficient, but when WebKit is open sourced you will also need to install QT (because WebKit uses QTMake and some other such tools).
Windows Configuration
You need to have the following tools installed:
- Cygwin. Some packages to make sure are installed are:
- openssh
- bison
- flex
- g++
- gperf
- make
- makedepend
- perl
- zip
- unzip
- DirectX SDK June 2010. Microsoft DirectX SDK (June 2010) headers are required for building the JavaFX SDK. This DirectX SDK can be downloaded from Microsoft DirectX SDK (June 2010). If the link above becomes obsolete, the SDK can be found from the Microsoft Download Site (search with "DirectX SDK June 2010"). The location of this SDK will normally be set with the environment variable DXSDK_DIR at installation time. The default location is normally "C:/Program Files/Microsoft DirectX SDK (June 2010)/". If DXSDK_DIR is not set, the build process may look for it in the default location or "C:/DXSDK/".
- Microsoft Visual Studio 10 (express edition works). The compiler and other tools are expected to reside in the location defined by the variableVS100COMNTOOLS which is set by the Microsoft Visual Studio installer.
Coming Soon: Gradle Build for OpenJFX
The OpenJFX team is working on a replacement for our current build and test system. We have chosen Gradle as the basis for this new system based on its IDE support, community support, flexibility, and great command line support. This new system is now far enough along to start testing. The documentation included here below is preliminary, but should provide enough guidance to give our gradle build system a good test.
Gradle is a build system which might be defined as a cross between Ant, Maven, and Rake. Like Ant, Gradle is designed primarily as a declarative means to build Java projects. In fact, Gradle has the ability to call into any Ant tasks. Like Maven, Gradle can automatically download and manage dependencies between projects and with library dependencies. In Fact, it can be configured to download from maven central and handle dependency management transparently. Like Rake, Gradle is a DSL. It is not XML based. In fact, Gradle is based on Groovy, which is a dynamic language for the JDK which shares its syntax with Java. In fact, a Groovy script can be written completely using valid Java code, or you can "groovify it" by, for example, removing semi-colons.
Our build is based on Gradle Version 1.4. This page is not a guide on using Groovy, nor is it a Gradle DSL reference. Rather, it is simply going to walk through using our new build system. If you already know Gradle, much of this will be self-explanatory. A different page will go into detail regarding how the build system works, so that anybody so (un)fortunate as to have to work on build files can get up to speed quickly
The prerequisites for using this document is to make sure you have downloaded Gradle 1.4 and installed it on your path. You must have successfully cloned openjfx, and must have already run the 'gradle -b generator.gradle' command in the rt repo. This will create a new sibling of rt called "javafx". All of the following assumes you are in this directory. In the next few months we will convert from our current project layout to the new one in the "javafx" directory, and these instructions will be modified accordingly.
Also, you need to have the native tools installed for native compilation.
Once you are setup and ready to go, the first thing you should do is generate the project files for your preferred IDE.
gradle netBeans
gradle idea
gradle eclipse
You can then leave the command line (hopefully forever!) and do all the rest of your work from within your IDE. No, really!
The "Gradle Support" module for NetBeans 7.3 was previously installed in my NetBeans instance. After running 'gradle netBeans', I then opened the javafx project with NetBeans and all of JavaFX is available for me and ready to go, even including native code. Its all there.
In order to perform a build from NetBeans, you simply have to hit the build button. To run a specific file (such as a sample), find the sample in the source tree (NOTE: Samples not setup yet as of 3/23/2013), right click and choose "run".
The experience in IDEA is similar. After running 'gradle idea', you open the "javafx" project. We will have already generated the project, workspace, and module settings for you. Many settings will have already been configured to be shared across all developers working on the project, such as the number of spaces per indent and the use of spaces instead of tabs.
IDEA and Eclipse differ from NetBeans in that they maintain their own compiled classes and maintain their own build. That is, while you can (and need to at times) run the Gradle build script in order to build, for example an SDK or the JavaDoc for the entire project or run all of the tests in the right way, most of the time you will end up just working in IDEA like you would for any other project. There are caveats though (such as making sure the JDK you have configured for the project does not have jfxrt.jar on its classpath!). This will all be documented separately.
You can setup a run configuration for any gradle tasks you want to. In this screenshot above, IDEA has been configured to execute the top-level clean run target. You can specify any environment variables or Gradle properties to feed to the build. This can be very convenient when you have different configurations you want to build for (for example, you might have a configuration for building normally and another for building iOS or ARM).
Most of the time you will be able to just work from within your IDE, doing building and testing. Even when you need to execute actually tasks in the OpenJFX Gradle build script, you can do it easily from within the IDE. However, for the sake of understanding the nuts and bolts (and to avoid having to take screenshots from all three IDEs for the rest of this document), I will switch to executing all commands from the command line. In fact, one of the advantages to Gradle over Ant is the fantastic command line interface it provides.
Using The Command Line
Before diving directly into building OpenJFX, lets get our feet wet by learning what kinds of things we can call from the command line, and how to get help when we need it. The first command you should execute is tasks:
rbair$ gradle tasks The CompileOptions.useAnt property has been deprecated and is scheduled to be removed in Gradle 2.0. There is no replacement for this property. :tasks ------------------------------------------------------------ All tasks runnable from root project ------------------------------------------------------------ Default tasks: assemble Basic tasks ----------- clean - Deletes the build directory and the build directory of all sub projects javadoc - Generates the JavaDoc for all the public API jfxrt - Creates the jfxrt.jar sdk - Creates an SDK Build tasks ----------- assemble - Assembles the outputs of this project. build - Assembles and tests this project. buildDependents - Assembles and tests this project and all projects that depend on it. buildNeeded - Assembles and tests this project and all projects it depends on. ccDecora - Compiles native sources for Decora ccGlass - Compiles native sources for Glass ccPrism - Compiles native sources for Prism ccPrismSW - Compiles native sources for PrismSW classes - Assembles the main classes. clean - Deletes the build directory. jar - Assembles a jar archive containing the main classes. javahDecora - Generates JNI Headers for Decora javahGlass - Generates JNI Headers for Glass javahPrism - Generates JNI Headers for Prism javahPrismSW - Generates JNI Headers for PrismSW linkDecora - Creates native dynamic library for Decora linkGlass - Creates native dynamic library for Glass linkPrism - Creates native dynamic library for Prism linkPrismSW - Creates native dynamic library for PrismSW native - Compiles and Builds all native libraries for Graphics nativeDecora - Generates JNI headers, compiles, and builds native dynamic library for Decora nativeGlass - Generates JNI headers, compiles, and builds native dynamic library for Glass nativePrism - Generates JNI headers, compiles, and builds native dynamic library for Prism nativePrismSW - Generates JNI headers, compiles, and builds native dynamic library for PrismSW stubClasses - Assembles the stub classes. testClasses - Assembles the test classes. Documentation tasks ------------------- javadoc - Generates Javadoc API documentation for the main source code. Help tasks ---------- dependencies - Displays all dependencies declared in root project 'javafx'. dependencyInsight - Displays the insight into a specific dependency in root project 'javafx'. help - Displays a help message projects - Displays the sub-projects of root project 'javafx'. properties - Displays the properties of root project 'javafx'. tasks - Displays the tasks runnable from root project 'javafx' (some of the displayed tasks may belong to subprojects). IDE tasks --------- cleanIdea - Cleans IDEA project files (IML, IPR) cleanIdeaWorkspace - Deletes the javafx.ipw file cleanNetBeans - Deletes generated NetBeans files idea - Generates IDEA project files (IML, IPR, IWS) netBeans - Creates the NetBeans project files for JavaFX Verification tasks ------------------ check - Runs all checks. test - Runs the unit tests. To see all tasks and more detail, run with --all. BUILD SUCCESSFUL Total time: 4.883 secs
The tasks task is extremely helpful. You use it to discover all the other things you can do with this build file. You notice at the top of the output the phrase "All tasks runnable from root project". The "root" project is "javafx". That is, we are in the root project. Below the root project are a series of sub projects, some of which are referred to as modules or "components". But more about those later.
Gradle then tells us what the default tasks are. In this case, our default task is the 'assembly' task. This is the task that will be executed if you just call 'gradle' alone without providing any additional arguments. After this comes a listing of different tasks, broken out by group. The first group is the "Basic" group which contains the tasks you may find yourself using most often. These are all named and have a description provided. For example, if I wanted to execute the 'clean' task, then I would do so like this:
rbair$ gradle clean
Finally, the tasks task gives us a useful hint that we can pass the --all argument in order to see all of the tasks in more detail. This produces a lot more output, but really gives an in depth look at what tasks are available for you to call.
I mentioned above that our root project is called "javafx", and that we have sub-projects in the gradle build. To see all of the projects available to you, execute the projects task (which you will notice was in the "Help tasks" group produced by the tasks task). This lists not just what projects are available, but what their name is, and what the project hierarchy is.
rbair$ gradle projects The CompileOptions.useAnt property has been deprecated and is scheduled to be removed in Gradle 2.0. There is no replacement for this property. :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project 'javafx' +--- Project ':base' +--- Project ':build-tools' +--- Project ':controls' +--- Project ':designTime' +--- Project ':fxml' +--- Project ':graphics' | +--- Project ':graphics:effects-jsl' | \--- Project ':graphics:prism-jsl' +--- Project ':swing' \--- Project ':swt' To see a list of the tasks of a project, run gradle <project-path>:tasks For example, try running gradle :base:tasks BUILD SUCCESSFUL Total time: 4.194 secs
Projects in gradle are named according to their depth. So the root project is simply named "javafx". The immediate subprojects are all prefixed with a ":". Sub-subprojects have their parents in their name, for example, ":graphics:effects-jsl". When you execute a command such as gradle assemble what actually happens is that Gradle locates the assemble task on all projects and executes them. (TODO Is this entirely accurate?)
There are a couple other tricks-of-the-trade that you should be aware of. You can execute any gradle command with --info or --debug in order to get more output. Running in --info mode provides some additional debugging output that is very useful when things go wrong. In particular, our build system will output certain crucial variables that are being used to perform the build:
rbair$ gradle projects Starting Build Settings evaluated using settings file '/Users/rbair/Projects/JavaFX/graphics-8.0/javafx/settings.gradle'. Projects loaded. Root project using build file '/Users/rbair/Projects/JavaFX/graphics-8.0/javafx/build.gradle'. Included projects: [root project 'javafx', project ':base', project ':build-tools', project ':controls', project ':designTime', project ':fxml', project ':graphics', project ':swing', project ':swt', project ':graphics:effects-jsl', project ':graphics:prism-jsl'] Evaluating root project 'javafx' using build file '/Users/rbair/Projects/JavaFX/graphics-8.0/javafx/build.gradle'. OS_NAME: mac os x JAVA_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0.jdk_b81/Contents/Home/jre JDK_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0.jdk_b81/Contents/Home BINARY_STUB: file:///Library/Java/JavaVirtualMachines/jdk1.8.0.jdk_b81/Contents/Home/jre/lib/ext/jfxrt.jar HUDSON_JOB_NAME: not_hudson HUDSON_BUILD_NUMBER: 0000 PROMOTED_BUILD_NUMBER: 00 PRODUCT_NAME: OpenJFX RAW_VERSION: 8.0.0 RELEASE_NAME: 8.0 RELEASE_MILESTONE: ea The CompileOptions.useAnt property has been deprecated and is scheduled to be removed in Gradle 2.0. There is no replacement for this property. Evaluating project ':base' using empty build file. Evaluating project ':build-tools' using empty build file. Evaluating project ':controls' using empty build file. Evaluating project ':designTime' using empty build file. Evaluating project ':fxml' using empty build file. Evaluating project ':graphics' using empty build file. Evaluating project ':swing' using empty build file. Evaluating project ':swt' using empty build file. Evaluating project ':graphics:effects-jsl' using empty build file. Evaluating project ':graphics:prism-jsl' using empty build file. All projects evaluated. Selected primary task 'projects' Tasks to be executed: [task ':projects'] :projects ------------------------------------------------------------ Root project ------------------------------------------------------------ Root project 'javafx' +--- Project ':base' +--- Project ':build-tools' +--- Project ':controls' +--- Project ':designTime' +--- Project ':fxml' +--- Project ':graphics' | +--- Project ':graphics:effects-jsl' | \--- Project ':graphics:prism-jsl' +--- Project ':swing' \--- Project ':swt' To see a list of the tasks of a project, run gradle <project-path>:tasks For example, try running gradle :base:tasks BUILD SUCCESSFUL Total time: 4.194 secs
Among all this output is a list of several important properties, such as JDK_HOME and BINARY_STUB. These properties are essential to the behavior of the build system, so if something goes wrong, you can check that you are building with the right binary stub and the right JDK (hint: nearly everything is based on JDK_HOME – if you have that set right, the rest of the Java build should just work).
One more trick is the --profile argument. You can perform any gradle task and use the --profile argument. This will cause gradle to keep track of how long various parts of the build took, and will produce an HTML report in build/reports/profile. The report breaks down how much time was spent in configuration, dependency resolution, and task execution. It further breaks it down by project. This gives useful metrics for tracking down which parts of the build take the longest and hopefully tighten up the build times.
Building OpenJFX
There are three main things you may want to do on a regular basis when working on JavaFX: building, testing, and creating documentation. Lets look at each of these in turn.
The simplest basic task to build is the sdk task. The sdk task will compile all Java sources and all native sources for your target platform. It will create the appropriate sdk directory and populate it with the native dynamic libraries and the jfxrt.jar. Because the SDK is not distributed with documentation, the javadocs are not created as part of the sdk task. Once the sdk task has completed, you will have and SDK distribution which you could run against (modulo any closed-bits) or give to somebody else to run.
rbair$ gradle sdk The CompileOptions.useAnt property has been deprecated and is scheduled to be removed in Gradle 2.0. There is no replacement for this property. :base:processVersion :build-tools:generateGrammarSource :build-tools:compileJava :build-tools:processResources :build-tools:classes :build-tools:jar :base:compileJava [snip out a whole bunch of stuff] :jfxrt :sdk BUILD SUCCESSFUL Total time: 1 mins 45.184 secs
You can find the built SDK in the build directory:
rbair$ pwd /Users/rbair/open-jfx/graphics/javafx rbair$ ls -l build/ drwxr-xr-x 3 rbair staff 102 Mar 23 17:39 mac-sdk drwxr-xr-x 3 rbair staff 102 Mar 23 17:39 tmp rbair$ ls build/mac-sdk/rt/lib/ ext/ libdecora-sse.dylib libprism-common.dylib javafx.properties libglass.dylib libprism-sw.dylib
The build is setup to support multiple different SDK builds. However, it is not possible to produce all SDKs from all platforms. For example, the win-sdk cannot be created from a Mac. However, on the Mac, you can compile the mac-sdk, ios-sdk, and android-sdk. On Linux you can compile linux-sdk, android-sdk, armhf-sdk, and armvpf-sdk. On Windows you can compile win-sdk and android-sdk. An attempt to build for a platform that is not supported will result in an error.
To compile for a specific target, set the COMPILE_TARGET property. This is usually done via a -P flag, such as:
rbair$ gradle -PCOMPILE_TARGET=ios sdk
If you do not specify the COMPILE_TARGET property, then the target will be picked based on what platform you are compiling from. At the present time only Linux x86, Windows, and Mac are platforms that you can compile from, but we would like to add support for compiling from Linux ARM as well (so that you can build the SDK on a Raspberry PI for example, which would be great for educational environments). At this time the following COMPILE_TARGET values are supported or planned:
- mac - Build for 64-bit Mac Desktop (min mac version 10.7)
- win - Build for 32 or 64-bit Windows*
- linux - Build for 32 or 64-bit Linux*
- ios
- swt - Builds an experimental implementation of Glass based on SWT (mostly for debug / perf testing)
- armhf - Builds for ARM Hard Float
- armvfp - Builds for ARM Soft Float (Virtual Floating Point)
- android - Builds for Android
Note* Right now you cannot specify whether you want 32 or 64, but that option is coming
Arguably the most important flag in the build is the JDK_HOME flag. Almost all other properties are derived automatically from this flag. THe JDK_HOME is by default based on the java.home System property, which is set automatically by the JVM based on which version of Java is executed. Typically, then, the version of Java you will be using to compile with will be the version of Java you have setup on your path. You can of course specify the JDK_HOME yourself (but be sure to include the file:// prefix or it will be treated as a relative path):
rbair$ gradle projects --info ... JDK_HOME: /Library/Java/JavaVirtualMachines/jdk1.8.0.jdk_b81/Contents/Home ... rbair$ gradle -PJDK_HOME=file:///Library/Java/JavaVirtualMachines/projects --info ... JDK_HOME: file:///Library/Java/JavaVirtualMachines/jdk1.8.0.jdk_b78/Contents/Home ...
The BINARY_STUB (see below), JAVA, JAVAC, and JAVAH properties are all derived from JDK_HOME, but can be specified directly if so needed (not likely). Another property, JDK_DOCS, is used to specify the URL to the JDK javadocs so that when the JavaFX javadocs are generated, any references to JDK classes will be hyperlinked.
There is also a COMPILE_FLAGS_FILE property. This flag is used to load a gradle file which is responsible for setting up the CC_PARAMS, LINK_PARAMS, CC, and LINK properties (and in the case of windows the RC property). For example, on Mac this property defaults to "mac.gradle", while on window it defaults to "win.gradle", and so forth. These supplemental gradle files contain all of the setup unique to those platforms for the sake of native compilation. But this property can be overridden such that a build for some custom system or to use some custom compiler could be made without modifying the core build script or requiring the build file to be stored in the open project. A third party might have some custom compiler or environment for an embedded system, for instance, and would need to customize the compilation flags.
Finally there are a number of properties which are used to define the values in the VersionInfo class. Typically these are set only from Hudson and include:
- HUDSON_JOB_NAME
- HUDSON_BUILD_NUMBER
- PROMOTED_BUILD_NUMBER
- PRODUCT_NAME
- RAW_VERSION
- RELEASE_NAME
- RELEASE_MILESTONE
The next basic task which you may want to perform is test. The test task will execute the unit tests. You generally will execute the top level test because unlike with Ant, Gradle will only re-execute those tests which have changed (or were dependent on code that was changed) on subsequent runs. You can of course execute gradle cleanTest in order to clean all the test results so they will run fresh. Or, if you want to execute only those tests related to a single project, you can do so in the normal fashion:
rbair$ gradle :base:test The CompileOptions.useAnt property has been deprecated and is scheduled to be removed in Gradle 2.0. There is no replacement for this property. :base:processVersion UP-TO-DATE :build-tools:generateGrammarSource UP-TO-DATE :build-tools:compileJava UP-TO-DATE :build-tools:processResources UP-TO-DATE :build-tools:classes UP-TO-DATE :build-tools:jar UP-TO-DATE :base:compileJava UP-TO-DATE :base:processResources UP-TO-DATE :base:classes UP-TO-DATE :base:compileTestJava UP-TO-DATE :base:processTestResources UP-TO-DATE :base:testClasses UP-TO-DATE > Building > :base:test > 3411 tests completed, 45 skipped
Gradle gives helpful output during execution of the number of tests completed and the number skipped without dumping out lots of output to the console (unless you opt for --info). Also, once the tests complete, an HTML report is dumped to the project's build/reports/test directory (for example, modules/base/build/reports/test):
For the sake of performance, most of the tests are configured to run in the same VM. However some tests by design cannot be run in the same VM, and others cannot yet run in the same VM due to bugs or issues in the test. In order to improve the quality of the project we need to run as many tests as possible in the same VM. The more tests we can run on pre-integration the less likely we are to see failures leak into master. Being able to run 20,000 tests in a minute is extremely useful, but not possible, unless they run in the same VM. Something to keep in mind.
The last of the basic tasks you might want to accomplish is the generation of javadoc. This is done by invoking the javadoc task. NOTE: At present there is a bug where gradle javadoc will fail, but gradle :javadoc succeeds. There really isn't much to say about the generation of javadoc, other than it works .
Unique Challenges of Working on the JDK
It is important to understand some unique challenges that come with building for the JDK. All Java developers have experience in building applications which rely on a specific JDK, but very few have attempted to build code for the JDK itself. Welcome to an elite band . As you know, when the JVM starts up, it locates classes on a class path. By default, all JDK classes are first on the class path, before any application code. Normally this is not a problem, because application code is not redefining java.lang.String, for example. However when building JDK code, that is exactly what you are doing. In the case of JavaFX, your version of javafx.scene.Node needs to take precedence over the version of javafx.scene.Node provided by the JDK. Further, since you need a version of the JDK available to build against, you have to deal with the problem of having two versions of most classes on your class path – those provided by the JDK you are building with and those you are providing yourself.
Over the years JDK engineers have developed various techniques for dealing with this problem. The issue manifests itself at two times: when you attempt to build, and when you attempt to run code. For now this document will cover the build part of the problem only. The good news is that the OpenJFX Gradle build handles this for you.
The main contributions of JavaFX to the JDK are the jfxrt.jar file and several native libraries. jfxrt.jar is located on the extension class path. This path comes before application code but after code on the boot class path. Because of this, the jfxrt.jar file is located in JDK_HOME/jre/lib/ext/ (ext here stands for 'extension'). Java allows developers to override the location of the ext directory by means of the -Djava.ext.dirs= command line argument. Setting the value of this argument to empty (i.e.: a dangling = sign with nothing after it) effectively clears the ext path. This means that the jfxrt.jar file shipped with the JDK won't be included on the class path by default.
This is how the OpenJFX Gradle build works. Whenever anything needs to be compiled (whether compiling java sources, or running javadoc) we always set the -Djavafx.ext.dirs flag to be empty. This way the code we're building isn't confused by the presence of another nearly identical set of classes on the ext class path (that is, our locally built jfxrt.jar and associated files take precedence over what is supplied by the JDK).
But, there is a wrinkle. Because OpenJFX is not yet completely buildable based on open software, we need to have the jfxrt.jar supplied by the most recent JDK available to us so that any classes or native libraries that we need for compiling and running (so-called 'closed bits' or 'binary stub') is available. But because JDK_HOME/jre/lib/ext/jfxrt.jar has duplicate classes to those we have built locally, we need to make sure that it is placed last on the class path – after all our own code. This way when the JVM is looking for javafx.scene.Node, it will find our version of javafx.scene.Node first, before the one supplied by the JDK. This, again, is handled for you by the Gradle build.
The OpenJFX Gradle build defines a property called BINARY_STUB, which is a path to a jar file containing the closed bits. This file is then added to the end of the class path when building. Ultimately this will not be needed anymore when the rest of the OpenJFX code is open sourced and a fully open build can be done. However for the moment, this is a requirement to get the build to succeed.
When running gradle normally, minimal output is produced. However if you run your gradle command with --info, additional information is printed at the head of the output, including the value of the BINARY_STUB variable. This must be a path to a copy of jfxrt.jar containing the closed bits. Most often this will be the jfxrt.jar file contained in your JDK_HOME/jre/lib/ext/ directory. Again, our build automatically figures this all out based on the value of your JDK_HOME (which by default is the version of Java you used to run the build).
Each week we produce a published "promoted" build of the JDK which includes the week's worth of changes to JavaFX. Generally speaking if you are building from the "master" OpenJFX forest, then you should always use the same corresponding version of the JDK. For example, on Mar 22 2013 we published b82 of the JDK. When building from OpenJFX master for the following week, use b82. This way the open bits and the closed bits are "matched" and your build will succeed.
During the week many changes go into the "graphics" or "controls" forests. It is possible that some corresponding changes are made to the closed bits during the week. This means when you try to build the "graphics" or "controls" forest, you will not have the corresponding "matched" closed bits available to you, and your build may fail. This situation is temporary and will last only until we have finished open sourcing all of the code.
So 9 paragraphs later, we get to the conclusion. You shouldn't have to do anything special to build OpenJFX for the "master" forest – just run gradle. However if you have a problem, the first step to debugging is to run the command with --info and look at the values of JDK_HOME and BINARY_STUB. If these are correct, make sure you have the right "matched" version of the JDK. You will most likely resolve any build problems by taking those steps. If you have additional build issues, let us know on the openjfx-dev mailing list.