...
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:
Code Block | ||||
---|---|---|---|---|
| ||||
rbair$ gradle -PCOMPILE_TARGETS=armv6hf |
Anchor | ||||
---|---|---|---|---|
|
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.
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Building and Running OpenJFX (Legacy Instructions)
(Note: These instructions are being revised for our new project layout & Gradle build. On June 28, 2013 we will have switch from ant to gradle as our build system, and these instructions will NO LONGER WORK. This page is being revised with the new instructions, and should be updated the first week of July)
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.
Widget Connector | ||
---|---|---|
|
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)
On Ubuntu Linux (tested on 12.04), the following command can be used to satisfy the prerequisites for this build:
sudo apt-get install mercurial ant libgtk2.0-dev libxtst-dev
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 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).
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.
And, proxies. If you're like us at Oracle and cursed to work behind a proxy, when using gradle you'll find it hangs while trying to download dependencies. What you need to do is create / edit your ~/.gradle/gradle.properties file:
Code Block |
---|
systemProp.http.proxyHost=<your proxy host here>
systemProp.http.proxyPort=<your proxy port here> |
Once you are setup and ready to tom you are can build by typing gradle in the 'javafx' directory:
Code Block |
---|
gradle |
Thats's all there is to it. You can now begin editing source files and doing command line development. If you are like us, you'll want to develop using your IDE of choice.
Coming Soon: Use your favourite IDE with OpenJFX
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.
IMPORTANT: Ensure that you do not have gradle plugins for NetBeans or Eclipse installed. They will conflict with the pre-generated IDE files. In furture, we may move to gradle builds within the IDE's as support becomes better.
Get a 32-bit version of the JDK
If you are building and running native libraries, the current native build produces 32-bit libraries. If you attempt to use them in a 64-bit JVM, they will fail to load and presently do not provide much indication about what went wrong. The easiest thing to do is to use a 32-bit JVM. This is not necessary on platforms like Mac that only support 64-bit JVM's.
Get an IDE that supports JDK8
OpenJFX is based on JDK1.8 and IDE support for lambdas and defender methods currently requires that you get a pre-release version. IntelliJ supports this out of the box. Eclipse and NetBeans do not.
IntelliJ: http://www.jetbrains.com/idea/download/
Eclipse: http://downloads.efxclipse.org/eclipse-java8/
NetBeans: http://bits.netbeans.org/dev/nightly/
- this version works on Mac: netbeans-trunk-nightly-201305192300-javase-macosx.dmg
- this version works on Windows: netbeans-trunk-nightly-201305192300-javase-windows.exe
- this versions works on Linux: netbeans-trunk-nightly-201306252301-javase-linux.sh
- other versions are likely to work but these are the ones that have been tested
Once you have downloaded and installed an IDE that is JDK8 aware, you will need to configure it to accept JDK8 syntax and generate the right byte codes. This will be explained later on for each particular IDE. If you use an IDE without JDK8 support, such as NetBeans 3.7.1, you will not be able to run from within the IDE.
Remove jfxrt.jar from the JDK
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 anything.
You can make a copy of your current JDK, remove the jar and tell your IDE to use this JDK instead. Another strategy is to keep the jar around but move it into a sibling 'ext2' directly so that paths can easily be changed manually to use it and you can restore quickly when necessary. Regardless, if you do not remove jfxrt.jar, you will get strange errors.
Another strategy is to copy it to an artifacts cache:
- cd <PATH TO JFX>
- mkdir -p artifacts/sdk/rt/lib/ext
- cp <PATH TO JDK>jre/lib/ext/jfxrt.jar artifacts/sdk/rt/lib/ext
IntelliJ
IntelliJ is a popular IDE that supports Java development. An IntelliJ project has been created for you that you need to open. The steps to use IntelliJ are:
- Open the IntelliJ Project
- Add jfxrt.jar to the Class Path
- Export the Jar to the other modules
- Make
- Run sample code
- Run sample code with grade built shared libraries (optional)
Open the IntelliJ Project
Add jfxrt.jar to the Class Path
Project Structure->Modules->buildSrc->Dependencies->+->Jars or Directories
Export the Jar to the other modules
Make
Build->Make Project
Run sample code
Run sample code with grade built shared libraries (optional)
//TODO - explain how to hook up the shared libraries in the run dialog
Eclipse
//TODO - document support
NetBeans
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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):
Code Block | ||||
---|---|---|---|---|
| ||||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Edit netbeans.conf
We have found the nightly versions of NetBeans to be unstable under JDK8, but fine otherwise. Further, NetBeans needs to be told not to report errors when private JDK classes referenced. The netbeans.conf file is located in the etc directory of your NetBeans install. You will edit netbeans_default_options and netbeans_jdkhome.
Here is a sample file from the Mac. The Windows and Linux default options might be a bit different.
# Options used by NetBeans launcher by default: # (can be overridden by explicit command line switches) # # Note that default -Xmx and -XX:MaxPermSize are selected for you automatically. # You can find these values in var/log/messages.log file in your userdir. # The automatically selected value can be overridden by specifying -J-Xmx or # -J-XX:MaxPermSize= here or on the command line. # # If you specify the heap size explicitly, you may also want to enable # Concurrent Mark & Sweep garbage collector. # (see http://wiki.netbeans.org/FaqGCPauses) # netbeans_default_options="-J-client -J-Xss2m -J-Xms32m -J-XX:PermSize=32m -J-Xmx1024m -J-da -J-DCachingArchiveProvider.disableCtSym=true -J-Dnetbeans.logger.console=true -J-Dapple.laf.useScreenMenuBar=true -J-Dapple.awt.graphics.UseQuartz=true -J-Dsun.java2d.noddraw=true -J-Dsun.java2d.dpiaware=true -J-Dsun.zip.disableMemoryMapping=true -J-Dplugin.manager.check.updates=false -J-Dnetbeans.extbrowser.manual_chrome_plugin_install=yes" # Default location of JDK: # (set by installer or commented out if launcher should decide) # # It can be overridden on command line by using --jdkhome <dir> # Be careful when changing jdkhome. # There are two NetBeans launchers for Windows (32-bit and 64-bit) and # installer points to one of those in the NetBeans application shortcut # based on the Java version selected at installation time. # netbeans_jdkhome="/Library/Java/JavaVirtualMachines/jdk1.7.0_11.jdk/Contents/Home"
Invoke NetBeans
Add the JDK8 Platform
Import the NetBeans Projects
Rebuild
Run Sample Code
Run Sample Code with gradle built shared libraries