(Note: We recently moved from an ant based build system to using Gradle. Further, we have performed a major restructuring of the project. Be aware that these instructions are current as of the end of June 2013 and do not apply to workspaces that were cloned prior to that time)
Building a UI toolkit for many different platforms is a complex and challenging endeavor. It requires platform specific tools such as C compilers as well as portable tools like Gradle. Which tools must be installed differs from platform to platform. While the OpenJFX build system was designed to remove as many build hurdles as possible, it is often necessary to build native code and have the requisite compilers and toolchains installed. On Mac and Linux this is fairly easy, but setting up Windows is more difficult.
Prerequisites
Since each release of OpenJFX is paired with a corresponding release of the JDK, you should make sure that you have a recent (preferably the latest) promoted build of the JDK available. For Java SE 8, these can be downloaded from the JDK 8 java.net page. Some make it a practice to always run against the latest promoted build, others will stick with an older build until they finally can't build OpenJFX with it anymore, and then update. Whichever method you chose, you need to have a reasonably recent version of JDK 8 installed.
OpenJFX, as with OpenJDK, uses Mercurial as the source control system. You must install some support for using Mercurial. Many (if not all) IDEs include built in support, although the tooling is generally not as good as you might get from a standalone tool. Popular options include SourceTree from Atlassian, TortoiseHg for Windows, or the command line tools from Mercurial.
You must also install Gradle. We are presently using Gradle v1.4, although we have heard reports that 1.5 and 1.6 also work.
Below are platform specific configuration instructions. Note that if all you want to do is hack on Java code, there is very little you need to configure (but testing becomes a little more difficult). Building only the JavaFX natives requires a little more in terms of tooling setup, but allows you to hack on Glass, Prism, and other native code. Setting up to build WebKit is the most work, and building WebKit takes the longest, but allows you to really build the whole thing an run an application completely on Open Source software.
Windows
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.
Mac
To configure your Mac, make sure you have at least version 10.7 installed. Install the latest version of Xcode and that you have the developer tools installed. You can install them by using the menus within Xcode: XCode -> Preferences -> Downloads -> Components. 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).
Linux
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
Getting the Sources
All OpenJFX sources are held in mercurial repositories. As mentioned in Repositories and Releases, we have several different repositories for you to choose from. If you are interested in building only the golden master (what is used for weekly promoted builds), then you would clone the master repository. If you are working on bug fixes for UI controls, then clone the controls repository. Otherwise, clone from graphics.
hg clone http://hg.openjdk.java.net/openjfx/8/graphics/rt
(Note: Historically you also had to clone the "jfx" repository in the forest that you cared about. However we have modified our approach, such that we no longer promote the use of a forest, and instead are putting all of our sources in a single repository, presently named "rt").
Using Gradle on 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 'sdk' 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.
Build and Test
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 is the default task which is executed if you do not supply a specific task to run. 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 by default. 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 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 sdk task will build an OpenJFX SDK for your particular Operating System. For example, on a Mac, this will produce build/mac-sdk and on windows build/win-sdk. Multiple different sdks may be built concurrently, and all will reside within the build directory when completed (see <<Cross Builds>> for more information). Gradle automatically handles the downloading of all dependencies (such as Antlr and SWT).
Invoking gradle without any additional parameters will skip the building of all native code. The reason for this default behavior is that most contributors to OpenJFX do not need to build native code for the contribution they are going to give, and most do not have the toolchains installed necessary to build the native code. Also, setting up the native toolchains on Windows is fairly difficult and error prone, and requiring all developers to cross this hurdle before they can contribute to OpenJFX is counter productive.
However, if you would like to build native code (but not GStreamer or WebKit) then you can invoke gradle passing this property:
gradle -PBUILD_NATIVES=true
For more information on build properties, see Customizing the Build.
Cross Builds
The build is configured to support cross builds, that is, the ability to build an SDK for a platform other than the one you are building from. There are multiple gradle files located in buildSrc which represent specific compile targets. These include:
- win.gradle
- mac.gradle
- linux.gradle
- android.gradle
- ios.gradle
- armv6sf.gradle
- armv6hf.gradle
Each of these have specific prerequisites that must be met before they can be built. win.gradle can only be used on Windows, mac.gradle on Mac, and linux.gradle on Linux. Android can be cross built from Mac, Windows, or Linux so long as the Android SDK and NDK are installed and the build knows where to find them. iOS can be cross built on Mac. ARM (soft float and hard float) can be cross built from Linux.
By default, the OpenJFX build system will only build the SDK for the desktop platform you are building from. To ask it to build for a specific compile target, you must pass a COMPILE_TARGETS property to the build system, instructing it which to build. This is a comma separated list. Assuming you have already setup the prerequisites for building ARM (for example, when targeting the Raspberry PI), you would invoke gradle like this:
rbair$ gradle -PCOMPILE_TARGETS=armv6hf
Cross building for ARM hard float
In order to cross-compile for Linux/ARM you first need to obtain the libraries to compile against. You'll need several of the same tools as for a Linux desktop build, so you should start by making sure you can build for the desktop, following the instructions above.
For the cross-compilation step you should start with a Raspberry Pi with the Raspbian operating system installed on it, as described at OpenJFX on the Raspberry Pi. Then you need to install some additional libraries:
sudo apt-get install \ libatk1.0-dev \ libdirectfb-dev \ libgtk2.0-dev \ libgstreamer0.10-dev \ libgstreamer-plugins-base0.10-dev \ libudev-dev \ libxml2-dev \ libxslt1-dev \ libxtst-dev
This will pull over the libraries from the Raspbian repository.
These instructions assume that you don't need to set an HTTP or HTTPS proxy to access the internet, either because you don't need one or because your system is already configured to use one. If you need to define proxy settings then you should define the environment variables http_proxy
and https_proxy
. Both are needed. In the case of the command with sudo
above, you need to define the proxy after sudo
, like this:
...
sudo http_proxy="http://<proxy-host>:<proxy-port" apt-get
Now you need to shut down the Pi (run sudo halt
and wait half a minute or so) and remove the SD card from it. Connect the card to a Linux x86 machine that has a working copy of OpenJFX on it. Then, from the OpenJFX directory run:
buildSrc/crosslibs/crosslibs-armv6hf.sh
This will copy files from your Pi's file system to a directory crosslibs
at the same level as your OpenJFX working copy. It will then download a cross-compiler for ARM and install it in the same place. When the script has completed you should see:
Done.
You can now replace your SD card in you Raspberry Pi; you won't need to run crosslibs-armv6hf.sh
again unless OpenJFX is modified to require additional or updated libraries.
You are now ready to run a full cross-compile for ARM hard float:
gradle -PBUILD_NATIVES=true -PCOMPILE_TARGETS=armv6hf
Note that when you run with an OpenJFX build you need to prepend your new jfxrt.jar
to the boot class path. For ARM cross-builds you also need to add jfxrt-graphics.jar
from an existing JDK. For example,
/opt/jdk1.8.0/bin/java \ -Xbootclasspath/p:build/armv6hf-sdk/rt/lib/ext/jfxrt.jar:\ /opt/jdk1.8.0/jre/lib/ext/jfxrt-graphics.jar \ -jar BrickBreaker.jar
This is so that you can use the closed source font libraries that are not available in OpenJFX. When we have a font implementation in OpenJFX using open source libraries this requirement will be removed.
Customizing the Build
The build can be customized fairly extensively through the use of Gradle properties. Gradle provides many ways to supply properties to the build system. However the most common approach will be to use a gradle.properties file located in the rt directory. Simply make a copy of gradle.properties.template and then edit the resulting gradle.properties file to customize your build.
rbair$ cp gradle.properties.template gradle.properties
The gradle.properties file that you have just created is heavily documented and contains information on all the different configuration options at your disposal. Some of the most common are:
- Enabling building of native source code (Prism, Glass, GStreamer, WebKit, etc)
- Specifying the build configuration (Release or Debug)
- Enabling building of JavaDoc
- Customizing the JDK_HOME
- Supplying compiler LINT options
Arguably the most important property in the build is the JDK_HOME property. Almost all other properties are derived automatically from this one. 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. Note also that on Windows, the version of the JDK you have set as JDK_HOME will determine whether you build 32 or 64 bit binaries.
Testing
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.