GraalVM Rules for Bazel

---

Latest release: 0.12.0

Use GraalVM with Bazel to:

• Build native binaries from polyglot apps
• Build native shared libraries from Java or polyglot code
• Use GraalVM as a Bazel Java toolchain
• Easily use GraalVM Maven artifacts
• Install components with gu

Additional features:

• Example projects for all use cases
• Hermetic compilation on all platforms
• Run tools from GraalVM directly
• Support for Bazel 6-8 (Bzlmod)
• Support for Bazel 4+, drop-in replacement for rules_graal
• Support for macOS, Linux, Windows (including Native Image!) (support matrix)
• Support for the latest modern GraalVM releases (Community Edition and Oracle GraalVM)

Getting Started

• Installation
• Examples
• Usage: Java Toolchains
• Usage: Native Image (Bazel 6+)
• Usage: Native Image (Bazel 4-6)
• Hermeticity & Strictness
• GraalVM Toolchains

Installation

API docs for graalvm_repository

Via WORKSPACE.bazel:

Artifact	SHA256
rules_graalvm-0.12.0.zip	``
rules_graalvm-0.12.0.tgz	``

http_archive(
    name = "rules_graalvm",
    sha256 = "",
    strip_prefix = "rules_graalvm-0.12.0",
    urls = [
        "https://github.com/sgammon/rules_graalvm/releases/download/v0.12.0/rules_graalvm-0.12.0.zip",
    ],
)

load("@rules_graalvm//graalvm:repositories.bzl", "graalvm_repository")

graalvm_repository(
    name = "graalvm",
    distribution = "ce",  # `oracle`, `ce`, or `community`
    java_version = "23",  # `17`, `20`, `22`, `23`, etc.
    version = "23.0.0",  # pass graalvm or specific jdk version supported by gvm
)

load("@rules_graalvm//graalvm:workspace.bzl", "register_graalvm_toolchains", "rules_graalvm_repositories")

rules_graalvm_repositories()

register_graalvm_toolchains()

Or, via MODULE.bazel:

Artifact	Integrity value
rules_graalvm-0.12.0.zip	``
rules_graalvm-0.12.0.tgz	``

bazel_dep(name = "rules_graalvm", version = "0.12.0")

gvm = use_extension("@rules_graalvm//:extensions.bzl", "graalvm")

gvm.graalvm(
    name = "graalvm",
    version = "23.0.0",  # pass graalvm or specific jdk version supported by gvm
    distribution = "ce",  # `oracle`, `ce`, or `community`
    java_version = "23",  # `17`, `20`, `22`, `23`, etc.
)
use_repo(gvm, "graalvm")
register_toolchains("@graalvm//:jvm")
register_toolchains("@graalvm//:sdk")

Examples

See the list of examples, which are used as continuous integration tests. Examples are available for Bazel 4-7.

Usage: Java Toolchains

You can use the graalvm_repository as a Java toolchain, by registering it like below:

Via WORKSPACE.bazel:

load("@rules_graalvm//graalvm:workspace.bzl", "register_graalvm_toolchains", "rules_graalvm_repositories")

rules_graalvm_repositories()

register_graalvm_toolchains()

Via Bzlmod:

register_toolchains("@graalvm//:jvm")
register_toolchains("@graalvm//:sdk")

To use the toolchain, add this to your .bazelrc:

build --extra_toolchains=@graalvm//:toolchain
build --java_runtime_version=graalvm_22

Note If you name your repository example and set the Java version to 21, your java_runtime_version would be example_21.

Usage: Native Image (Bazel 6+)

API docs for native_image

In a BUILD.bazel file:

load("@rules_java//java:defs.bzl", "java_library")
load("@rules_graalvm//graalvm:defs.bzl", "native_image")

java_library(
    name = "main",
    srcs = glob(["Main.java"]),
)

native_image(
    name = "main-native",
    deps = [":main"],
    main_class = "Main",
    native_image_tool = "@graalvm//:native-image",
)

Native image toolchains

It is supported to specify the native-image tool as above, using the native_image_tool attribute on your target. In fact, you must do this unless you register the GraalVM toolchains as shown in the installation instructions.

When using toolchains, the native_image_tool attribute can be omitted, which delegates to Bazel's toolchain system to resolve the tool:

Resolve via toolchains:

native_image(
    name = "main-native",
    deps = [":main"],
    main_class = "Main",
)

Or point to a specific native-image tool:

native_image(
    name = "main-native",
    deps = [":main"],
    main_class = "Main",
    native_image_tool = "@graalvm//:native-image",
)

Usage: Native Image (Bazel 4 & 5)

API docs for legacy native_image rule

In a BUILD.bazel file:

load("@rules_java//java:defs.bzl", "java_library")
load("@rules_graalvm//graal:graal.bzl", "native_image")

java_library(
    name = "main",
    srcs = glob(["Main.java"]),
)

native_image(
    name = "main-native",
    deps = [":main"],
    main_class = "Main",
)

Important

In the legacy rules, you don't have to specify native_image_tool, but on the other hand, the default target @graalvm//:native-image is hard-coded in. If you use a different repository name make sure to add the native_image_tool attribute to point to @yourrepo//:native-image.

Hermeticity & Strictness

These rules attempt to strike as optimal a balance as possible between older Bazel support (starting at Bazel 4) and the maximum possible strictness/hermeticity for action execution.

Bazel Toolchains are used to resolve the C++ compiler which is provided to native-image. Toolchains are additionally used within the rules to provide and resolve tools from GraalVM itself.

For information about strictness tuning on each operating system, see the hermeticity guide.

GraalVM toolchain type

The GraalVM-specific toolchain type is available at:

@rules_graalvm//graalvm/toolchain:toolchain_type

If you install GraalVM at a repository named @graalvm, the toolchain targets are:

Java toolchain:

@graalvm//:jvm

GraalVM toolchain:

@graalvm//:sdk

The default WORKSPACE and Bzlmod installation instructions register both types of toolchains. The GraalVM toolchain is required to perform builds with native-image (or you must provide a native_image_tool target).

Adoption

rules_graalvm is used in the following organizations and in Bazel itself, as part of the Turbine toolchain.

If you are using rules_graalvm, let us know with a PR!

Bazel uses rules_graalvm for Native Turbine.

Netflix apparently uses it somehow.

Elide uses rules_graalvm as part of the tooling for the Elide Runtime, and for Buildless.

Acknowledgements

Built on top of @andyscott's fantastic work with rules_graal. Several contributors helped greatly, especially with regard to Bazel's toolchains and C++ features: @fmeum and others.