Graal is a dynamic compiler written in Java that integrates with the HotSpot JVM. It has a focus on high performance and extensibility. In addition, it provides optimized performance for Truffle-based languages running on the JVM.
Working with Graal will mean cloning more than one repository and so it's recommended to create and use a separate directory:
mkdir graal
cd graal
To simplify Graal development, a separate Python tool called mx has been co-developed. This tool must be downloaded and put onto your PATH:
git clone https://github.com/graalvm/mx.git
export PATH=$PWD/mx:$PATH
Graal depends on a JDK that supports JVMCI (JVM Compiler Interface). Graal should work out of the box with JDK 9 or later. JVMCI-enabled builds of JDK 8 for selected platforms are available via OTN. If you are not on one of these platforms (e.g., Windows), see Building JVMCI JDK 8 below. Note that these other platforms are not regularly tested so your mileage may vary.
Once you have installed (or built) a JVMCI-enabled JDK, ensure JAVA_HOME is pointing at the JDK home directory (or at <jdk_home>/Contents/Home on Mac OS X if the JDK has this layout).
Graal also depends on Truffle which needs to be cloned along with Graal.
git clone https://github.com/graalvm/graal.git
cd graal/compiler
mx
Changing to the graal/compiler directory informs mx that the focus of development (called the primary suite) is Graal.
All subsequent mx commands should be executed from this directory.
Here's the recipe for building and running Graal (if on Windows, replace mx with mx.cmd):
mx build
mx vm
By default, Graal is only used for hosted compilation (i.e., the VM still uses C2 for compilation).
To make the VM use Graal as the top tier JIT compiler, add the -XX:+UseJVMCICompiler option to the command line.
To disable use of Graal altogether, use -XX:-EnableJVMCI.
You can generate IDE project configurations by running:
mx ideinit
This will generate Eclipse, IntelliJ, and NetBeans project configurations. Further information on how to import these project configurations into individual IDEs can be found on the IDEs page.
The Graal code base includes the Ideal Graph Visualizer which is very useful in terms of visualizing Graal's intermediate representation (IR). You can get a quick insight into this tool by running the commands below. The first command launches the tool and the second runs one of the unit tests included in the Graal code base with extra options to make Graal dump the IR for all methods it compiles. You should wait for the GUI to appear before running the second command.
mx igv &
mx unittest -Dgraal.Dump BC_athrow0
If you added -XX:+UseJVMCICompiler as described above, you will see IR for compilations requested by the VM itself in addition to compilations requested by the unit test.
The former are those with a prefix in the UI denoting the compiler thread and id of the compilation (e.g., JVMCI CompilerThread0:390).
Further information can be found on the Debugging page.
For video tutorials, presentations and publications on Graal visit the Publications page.
To create a JVMCI enabled JDK 8 on other platforms (e.g., Windows):
git clone https://github.com/graalvm/graal-jvmci-8
cd graal-jvmci-8
mx --java-home /path/to/jdk8 build
mx --java-home /path/to/jdk8 unittest
export JAVA_HOME=$(mx --java-home /path/to/jdk8 jdkhome)
You need to use the same JDK the OTN downloads are based on as the argument to --java-home in the above commands.
The build step above should work on all supported JDK 8 build platforms.
It should also work on other platforms (such as Oracle Linux, CentOS and Fedora as described here).
If you run into build problems, send a message to the Graal mailing list.
The Graal compiler is licensed under the GPL 2.