Get started with GraalVM and configure it to run programs written in Java (or other JVM-based languages), JavaScript and Node.js, Ruby, R, or Python. This page guides you through downloading and installing GraalVM and adding support for additional languages, and shows you how to run simple programs on GraalVM.
Download GraalVM
GraalVM is a standalone Java Development Kit that you can use for executing Java or JVM-based applications, as well as applications written in JavaScript, Python, Ruby, and R, with its polyglot language engines. The current release is based on the OpenJDK 8 and contains JavaScript (including Node.js) as a pre-installed extension language. GraalVM implementations of the R, Ruby and Python scripting languages can be installed as additional components per need. There are Community and Enterprise GraalVM editions available for download. Proceed to the Downloads page and make your choice depending on your operating system and use case.
In this getting started guide we will focus on working with the GraalVM archive obtained from the Oracle Technology Network, called the GraalVM Enterprise Edition. Similar to the Community Edition, this includes the JVM, the Graal compiler, the LLVM interpreter and the JavaScript runtime with Node.js support – all in one package.
Install GraalVM
GraalVM Enterprise Edition supports Linux and Mac OS X on x86 64-bit systems. Getting GraalVM installed and ready-to-go should only take a few minutes.
- Navigate to Downloads page, choose Enterprise edition, proceed to the Oracle Technology Network, accept the license and download the archive.
- Extract the archive to your file system.
- Add the GraalVM
/bin
folder to yourPATH
, for example on Linux:export PATH=/path/to/graalvm/bin:$PATH
and on Mac OS:
export PATH=/path/to/graalvm/Contents/Home/bin:$PATH
- You can verify whether you are using GraalVM with the echo command:
echo $PATH
.
Optionally set the JAVA_HOME
environment variable to resolve to the GraalVM installation directory.
You can also specify GraalVM as the JRE or JDK installation in your Java IDE.
GraalVM’s /bin
directory is similar to that of a standard JDK, but includes a set of additional launchers:
- js runs a JavaScript console with GraalVM.
- node is a drop-in replacement for Node.js, using GraalVM’s JavaScript engine.
- lli is a high-performance LLVM bitcode interpreter integrated with GraalVM.
- native-image builds an ahead-of-time compiled executable or a shared library from Java applications.
- gu (Graal updater) can be used to install language packs for Python, R, and Ruby.
Notably, java in GraalVM runs the JVM with Graal as the default compiler. The Ruby, Python and R executables become available only if you install the corresponding language engines. For example, running the following command will install Ruby support:
gu install ruby
For more information on using Graal updater please refer to its documentation.
Once the PATH
environment variable is set properly, it’s easy to check language versions with GraalVM launchers:
$ java -version
java version "1.8.0_192"
Java(TM) SE Runtime Environment (build 1.8.0_192-b12)
GraalVM 1.0.0-rc12 (build 25.192-b12-jvmci-0.54, mixed mode)
$ node -v
v10.15.0
$ lli --version
Graal llvm 6.0.0 (GraalVM EE Native 1.0.0-rc12)
If you have, e.g., the Ruby language component installed, you can check its version as well:
$ ruby -v
truffleruby 1.0.0-rc12, like ruby 2.4.4, GraalVM CE Native [x86_64-darwin]
GraalVM Docker Containers
The official Docker images for GraalVM CE are available from the Docker Hub: https://hub.docker.com/r/oracle/graalvm-ce/.
If you want to use the Docker container with GraalVM CE, use the docker pull
command:
docker pull oracle/graalvm-ce:1.0.0-rc12
The image is based on Oracle Linux and has GraalVM CE downloaded, unzipped and made available. It means that Java, JavaScript, Node and the LLVM interpreter are available out of the box.
You can start a container and enter the bash
session with the following run command:
docker run -it oracle/graalvm-ce:1.0.0-rc12 bash
Check that java
, js
and other commands work as expected.
→ docker run -it oracle/graalvm-ce:1.0.0-rc12 bash
bash-4.2# java -version
openjdk version "1.8.0_192"
OpenJDK Runtime Environment (build 1.8.0_192-20181024121959.buildslave.jdk8u-src-tar--b12)
GraalVM 1.0.0-rc12 (build 25.192-b12-jvmci-0.54, mixed mode)
bash-4.2# node
> 1 + 1
2
> process.exit()
bash-4.2# lli --version
Graal llvm 6.0.0 (GraalVM CE Native 1.0.0-rc12)
bash-4.2#
Please note that the image contains only the components immediately available in the GraalVM CE distribution. However, the Graal updater utility is on the path. You can install the support for additional languages like Ruby, R, or Python at will. For example, the following command installs the Ruby support (the output below is truncated for brevity):
docker run -it oracle/graalvm-ce:1.0.0-rc12 bash
bash-4.2# gu install ruby
Downloading: Component catalog
Processing component archive: Component ruby
Downloading: Component ruby
[###### ]
...
If you want to mount a directory from the host system to have it locally available in the container, use Docker volumes.
Here is a sample command that maps the /absolute/path/to/dir/no/trailing/slash
directory from the host system to the /path/inside/container
inside the container.
docker run -it -v /absolute/path/to/dir/no/trailing/slash:/path/inside/container oracle/graalvm-ce:1.0.0-rc12 bash
If you want to create docker images that contain GraalVM Ruby, R, or Python implementation, you can use dockerfiles like the example below, which uses oracle/graalvm-ce:1.0.0-rc12
as the base image, installs Ruby support using the gu
utility, then creates and runs a sample Ruby program.
FROM oracle/graalvm-ce:1.0.0-rc12
RUN gu install ruby
WORKDIR /workdir
RUN echo 'puts "Hello from Truffleruby!\nVersion: #{RUBY_DESCRIPTION}"' > app.rb
CMD ruby app.rb
If you put the above snippet in the Dockerfile
in the current directory,
you can build and run it with the following commands.
docker build -t truffleruby-demo .
...
$ docker run -it --rm truffleruby-demo
Hello from Truffleruby!
Version: truffleruby 1.0.0-rc12, like ruby 2.4.4, GraalVM CE Native [x86_64-linux]
Running Applications
Since the executables of all language runtimes in GraalVM emulate the behavior of the languages’ default runtimes, putting GraalVM on your PATH
should be enough to run your applications with GraalVM.
Running Java
Take a look at this typical HelloWorld
class:
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
Run the following command to compile this class to bytecode and then run it on GraalVM:
$ javac HelloWorld.java
$ java HelloWorld
Hello World!
You can find a collection of larger examples of Java applications you can try running with GraalVM on the examples page.
Running JavaScript
GraalVM can execute plain JavaScript code, both in REPL mode and by executing script files directly.
$ js
> 1 + 2
3
GraalVM also supports running Node.js applications. More than 45.000 npm modules are tested and are fully compatible with GraalVM, including modules like express, react, async, request, browserify, grunt, mocha, and underscore.
To install a Node.js module, use the npm
executable in the /bin
folder of the
GraalVM package. The npm
command is equivalent to the default Node.js
command and supports all Node.js APIs.
1. Install the colors
and ansispan
modules using npm install
:
npm install colors ansispan
After the modules are installed, you can use them from your application.
2. Add the following code snippet to a file named app.js
and save it in the same directory where you installed the Node.js modules:
// RUN-CMD: rm -rf node_modules
// RUN-CMD: npm install ansispan colors
// RUN-CMD: node {file}
// RUN-CMD: rm -r node_modules
// BEGIN-SNIPPET
const http = require("http");
const span = require("ansispan");
require("colors");
http.createServer(function (request, response) {
response.writeHead(200, {"Content-Type": "text/html"});
response.end(span("Hello Graal.js!".green));
}).listen(8000, function() { console.log("Graal.js server running at http://127.0.0.1:8000/".red); });
// END-SNIPPET
setTimeout(function() { console.log("DONE!"); process.exit(); }, 2000);
3. Execute it on GraalVM using the node
command:
node app.js
More information on compatibility with the Node.js and configuring GraalVM read the reference manual on JavaScript in GraalVM.
Running LLVM Interpreter
The LLVM interpreter in GraalVM executes LLVM bitcode, and therefore any programming language that can be compiled to LLVM bitcode.
Put this C HelloWorld
into a file named hello.c
:
#include <stdio.h>
int main() {
printf("Hello from GraalVM!\n");
return 0;
}
You can compile hello.c
to an LLVM bitcode file named hello.bc
using the following command:
$ clang -c -O1 -emit-llvm hello.c
You can then run hello.bc
on GraalVM like this:
$ lli hello.bc
Hello from GraalVM!
More examples and information on what languages and runtimes are supported can be found in the reference manual for LLVM.
Running Ruby
The Ruby engine is not installed by default, but it can easily be added using the Graal updater:
gu install ruby
This makes Ruby commands like ruby
, gem
, irb
, rake
, rdoc
and ri
available:
$ ruby [options] program.rb
GraalVM’s Ruby implementation uses the same options as the standard implementation of Ruby, with some additions.
$ gem install chunky_png
$ ruby -r chunky_png -e "puts ChunkyPNG::Color.to_hex(ChunkyPNG::Color('mintcream @ 0.5'))"
#f5fffa80
Using Bundler
The only supported version of Bundler at the moment is 1.16.x
.
$ gem install bundler -v 1.16.3
$ bundle exec ...
More examples and additional information on Ruby support in GraalVM can be found in the reference manual for Ruby.
Running R
The R engine is not installed by default, but it can easily be added using the Graal updater:
gu install r
When the R engine is installed, you can execute R scripts and use the R REPL with GraalVM:
$ R
R version 3.5.1 (FastR)
...
> 1 + 1
[1] 2
More examples and additional information on R support in GraalVM can be found in the reference manual for R.
Running Python
GraalVM implementation of Python 3.7 has recently been started. The Python engine is not installed by default, but it can easily be added using the Graal updater:
gu install python
Once the Python engine is installed, GraalVM can execute Python programs:
$ graalpython
...
>>> 1 + 2
3
>>> exit()
More examples and additional information on Python support in GraalVM can be found in the reference manual for Python.
Combine Languages
If enabled, using the --polyglot
flag, scripts executed on GraalVM can use interoperability features to call into other languages and exchange data with them.
For example, running js --jvm --polyglot example.js
executes example.js
in a polyglot context.
If the program calls any code in other supported languages, GraalVM executes that code in
the same runtime as the example.js
application. For more information on polyglot applications see the polyglot documentation.
Native Images
GraalVM can compile Java bytecode into native images to achieve faster startup and smaller footprint for your applications.
Let’s use the HelloWorld
example from above to demonstrate how to compile Java bytecode into a native image:
// HelloWorld.java
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
Run the following to compile the class to bytecode and then build a native image:
$ javac HelloWorld.java
$ native-image HelloWorld
This builds an executable file named helloworld
in the current working directory.
Invoking it executes the natively compiled code of the HelloWorld
class as follows:
$ ./helloworld
Hello, World!
Polyglot Capabilities of Native Images
The native-image
tool also makes it easy to use polyglot capabilities.
Take this example of a JSON pretty-printer using the GraalVM implementation of JavaScript:
// PrettyPrintJSON.java
import java.io.*;
import java.util.stream.*;
import org.graalvm.polyglot.*;
public class PrettyPrintJSON {
public static void main(String[] args) throws java.io.IOException {
BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
String input = reader.lines().collect(Collectors.joining(System.lineSeparator()));
try (Context context = Context.create("js")) {
Value parse = context.eval("js", "JSON.parse");
Value stringify = context.eval("js", "JSON.stringify");
Value result = stringify.execute(parse.execute(input));
System.out.println(result.asString());
}
}
}
The --language:js
argument ensures that the JavaScript engine is available in the generated image:
$ javac PrettyPrintJSON.java
$ native-image --language:js PrettyPrintJSON
This native executable can now perform JSON pretty printing:
$ ./prettyprintjson <<EOF
{"GraalVM":{"description":"Language Abstraction Platform","supports":["combining languages","embedding languages","creating native images"],"languages": ["Java","JavaScript","Node.js", "Python", "Ruby","R","LLVM"]}}
EOF
Here is the JSON output from the native executable:
{
"GraalVM": {
"description": "Language Abstraction Platform",
"supports": [
"combining languages",
"embedding languages",
"creating native images"
],
"languages": [
"Java",
"JavaScript",
"Node.js",
"Python",
"Ruby",
"R",
"LLVM"
]
}
}
The native image is much faster than running the same code on the JVM directly:
$ time bin/java PrettyPrintJSON < test.json > /dev/null
real 0m1.101s
user 0m2.471s
sys 0m0.237s
$ time ./prettyprintjson < test.json > /dev/null
real 0m0.037s
user 0m0.015s
sys 0m0.016s
There are certain limitations of ahead-of-time compilation with GraalVM, listed here.
What to read next?
If you want to learn what GraalVM offers to different types of teams, read the Why Graal page. Some of the diverse features of GraalVM are disclosed and supported with examples in Top 10 Things To Do With GraalVM article. Or, you can examine different supported languages in action by looking at example applications. If you want to learn about the common tools GraalVM enables for the supported languages, proceed to the tools section of the reference manual. And if you are mostly interested in a specific language, more extensive documentation is available in the reference manual as well.