◀Table of Contents
Get Started with GraalVM
Get started with GraalVM – is a high-performance JDK designed to accelerate Java application performance while consuming fewer resources. GraalVM offers two ways to run Java applications: on the HotSpot JVM with Graal just-in-time (JIT) compiler or as an ahead-of-time (AOT) compiled native executable. Besides Java, it provides runtimes for JavaScript, Ruby, Python, and a number of other popular languages. GraalVM’s polyglot capabilities make it possible to mix programming languages in a single application while eliminating any foreign language call costs.
Here you will find information about installing GraalVM Community Edition, running basic applications with it, and adding support for accompanying features. Further, you will learn about the polyglot capabilities of GraalVM and see how to build platform-specific native executables of Java applications.
If you are new to GraalVM, we recommend starting with Introduction to GraalVM, where you will find information about GraalVM’s architecture, distributions available, supported platforms, core and additional features, and much more.
If you have GraalVM already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth Reference Manuals.
Install GraalVM
Getting GraalVM installed and ready-to-go should take a few minutes. Choose the operating system and proceed to the installation steps:
Start Running Applications
The core distribution of GraalVM includes the JVM and the GraalVM compiler. Having downloaded and installed GraalVM, you can already run any Java application unmodified.
Other languages support can be installed on request, using gu – the GraalVM Updater tool to install additional language runtimes and utilities. Further below you will find information on how to add other optionally available GraalVM runtimes including JavaScript, Node.js, LLVM, Ruby, R, Python, and WebAssembly.
Run Java
The java launcher runs the JVM with the GraalVM default compiler - Graal.
Check the Java version upon the installation:
$GRAALVM_HOME/bin/java -version
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 commands to compile this class to bytecode and then execute it:
javac HelloWorld.java
java HelloWorld
Hello World!
You can find a collection of larger Java examples on the Examples Applications page. For more information on the GraalVM compiler, go to Compiler. For more extensive documentation on running Java, proceed to JVM Languages.
Run JavaScript and Node.js
GraalVM supports running JavaScript applications. The JavaScript runtime is optionally available and can be installed with this command:
gu install js
It installs the js launcher in the $GRAALVM_HOME/bin directory.
With the JavaScript runtime installed, you can execute plain JavaScript code, both in REPL mode and by executing script files directly:
$GRAALVM_HOME/bin/js
> 1 + 2
3
GraalVM also supports running Node.js applications. The Node.js support is not installed by default, but can be easily added with this command:
gu install nodejs
Both node and npm launchers then become available in the $GRAALVM_HOME/bin directory.
$GRAALVM_HOME/bin/node -v
$GRAALVM_HOME/bin/npm show <package name> version
More than 100,000 npm packages are regularly tested and are 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 from $GRAALVM_HOME/bin, which is installed together with node.
The npm command is equivalent to the default Node.js command and supports all Node.js APIs.
Install the modules colors, ansispan, and express using npm install.
After the modules are installed, you can use them from your application.
$GRAALVM_HOME/bin/npm install colors ansispan express
Use the following code snippet and save it as the app.js file in the same directory where you installed the Node.js modules:
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); });
setTimeout(function() { console.log("DONE!"); process.exit(); }, 2000);
Run app.js on GraalVM Enterprise using the node command:
$GRAALVM_HOME/bin/node app.js
For more detailed documentation and information on compatibility with Node.js, proceed to JavaScript and Node.js.
Run LLVM Languages
The GraalVM LLVM runtime can execute C/C++, Rust, and other programming languages that can be compiled to LLVM bitcode.
The LLVM runtime is optionally available and can be installed with this command:
$GRAALVM_HOME/bin/gu install llvm
It installs the GraalVM implementation of lli in the $GRAALVM_HOME/bin directory.
Check the version upon the installation:
$GRAALVM_HOME/bin/lli --version
With the LLVM runtime installed, you can execute programs in LLVM bitcode format on GraalVM.
To compile a native program to LLVM bitcode, you use some LLVM frontend, for example clang.
Besides the LLVM runtime, GraalVM also provides the LLVM frontend (toolchain) that you can set up as follows:
gu install llvm-toolchain
export LLVM_TOOLCHAIN=$(lli --print-toolchain-path)
Then the C/C++ code can be compiled to LLVM bitcode using clang shipped with GraalVM.
For example, put this C code into a file named hello.c:
#include <stdio.h>
int main() {
printf("Hello from GraalVM!\n");
return 0;
}
Compile hello.c to an executable hello with embedded LLVM bitcode and run it:
$LLVM_TOOLCHAIN/clang hello.c -o hello
lli hello
For in-depth documentation about the GraalVM LLVM runtime, go to LLVM Languages.
Run Python
With GraalVM you can run Python applications in the Python 3 runtime environment. The support is not available by default, but you can quickly add it to GraalVM with this command:
gu install python
It installs the graalpython launcher. Check the version, and you can already run Python programs:
$GRAALVM_HOME/bin/graalpython --version
$GRAALVM_HOME/bin/graalpython
...
>>> 1 + 2
3
>>> exit()
More examples and additional information on Python support in GraalVM can be found in the Python reference manual.
Run Ruby
GraalVM provides a high-performance Ruby runtime environment including the gem command that allows you to interact with RubyGems, Ruby Bundler, and much more.
The Ruby runtime is not available by default in GraalVM, but can be easily added with this command:
gu install ruby
Once it is installed, Ruby launchers like ruby, gem, irb, rake, rdoc, and ri become available to run Ruby programs:
$GRAALVM_HOME/bin/ruby [options] program.rb
GraalVM runtime for Ruby uses the same options as the standard implementation of Ruby, with some additions. For example:
gem install chunky_png
$GRAALVM_HOME/bin/ruby -r chunky_png -e "puts ChunkyPNG::Color.to_hex(ChunkyPNG::Color('mintcream @ 0.5'))"
#f5fffa80
More examples and in-depth documentation can be found in the Ruby reference manual.
Run R
GraalVM provides a GNU-compatible environment to run R programs directly or in the REPL mode. Although the R language support is not available by default, you can add it to GraalVM with this command:
gu install R
When the language is installed, you can execute R scripts and use the R REPL:
$GRAALVM_HOME/bin/R
...
> 1 + 1
[1] 2
More examples and in-depth documentation can be found in the R reference manual.
Run WebAssembly
With GraalVM you can run programs compiled to WebAssembly. The support is not available by default, but you can add it to GraalVM with this command:
gu install wasm
Then the wasm launcher, that can run compiled WebAssembly binary code, becomes available.
For example, put the following C program in a file named floyd.c:
#include <stdio.h>
int main() {
int number = 1;
int rows = 10;
for (int i = 1; i <= rows; i++) {
for (int j = 1; j <= i; j++) {
printf("%d ", number);
++number;
}
printf(".\n");
}
return 0;
}
Compile it using the most recent Emscripten compiler frontend version. It should produce a standalone floyd.wasm file in the current working directory:
emcc -o floyd.wasm floyd.c
Then you can run the compiled WebAssembly binary on GraalVM as follows:
$GRAALVM_HOME/bin/wasm --Builtins=wasi_snapshot_preview1 floyd.wasm
More details can be found in the WebAssembly reference manual.
Combine Languages
GraalVM allows you to call one programming language into another and exchange data between them.
To enable interoperability, GraalVM provides the --polyglot flag.
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 running polyglot applications, see Polyglot Programming.
Native Image
With GraalVM you can compile Java bytecode into a platform-specific, self-contained, native executable to achieve faster startup and smaller footprint for your application. GraalVM Native Image functionality is not available by default, but can be easily installed with the GraalVM Updater tool:
gu install native-image
The HelloWorld example from above is used here to demonstrate how to generate a native executable:
// HelloWorld.java
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
Note: For compilation the
native-imagetool depends on the local toolchain. Make sure your system meets the prerequisites.
Compile HelloWorld.java to bytecode and then build a native executable:
javac HelloWorld.java
native-image HelloWorld
The last command generates 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!
More detailed documentation on this innovative technology is available in the Native Image reference manual.
Polyglot Capabilities of Native Image
GraalVM makes it possible to use polyglot capabilities when building native executables. Take this example of a JSON pretty-printer Java program that embeds some JavaScript code:
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), null, 2);
System.out.println(result.asString());
}
}
}
Compile it and build a native executable for it.
The --language:js argument ensures that JavaScript is available in the generated executable:
javac PrettyPrintJSON.java
native-image --language:js --initialize-at-build-time PrettyPrintJSON
The generatation of a native executable will take several minutes as it does not just build the PrettyPrintJSON class, but also builds JavaScript.
Additionally, the building requires large amounts of physical memory, especially if you build a native executable with the Truffle language implementation framework included, which is the case here.
The generatation will take several minutes as it does not just build the PrettyPrintJSON class, but also builds JavaScript.
Additionally, the generatation requires large amounts of physical memory, especially if you build a native executable with
the Truffle language implementation framework included, which is the case here.
The resulting binary 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 executable runs 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
What to Read Next
New Users
Since this guide is intended mainly for users new to GraalVM, or users who are familiar with GraalVM but may have little experience using it, please consider investigating more complex Example Applications. We also recommend checking our GraalVM Team Blog.
Advanced Users
If you are mostly interested in GraalVM support for a specific language, or want more in-depth details about GraalVM’s diverse technologies, proceed to Reference Manuals.
If you are looking for the tooling support GraalVM offers, proceed to Debugging and Monitoring Tools.
If you are considering GraalVM as a platform for your future language or tool implementation, go to GraalVM as a Platform.
You can find information on GraalVM’s security model in the Security Guide, and rich API documentation in GraalVM SDK Javadoc and Truffle Javadoc.