Skip to content

Latest commit

 

History

History
305 lines (214 loc) · 11.7 KB

README.md

File metadata and controls

305 lines (214 loc) · 11.7 KB
Raw

GraalVM Rules for Bazel

Bazel 7 Bzlmod CI Contributor Covenant OpenSSF Best Practices OpenSSF Scorecard

Latest release: 0.12.0

Use GraalVM with Bazel to:

Additional features:

Getting Started

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!


Google logo

Bazel uses rules_graalvm for Native Turbine.


Netflix logo

Netflix apparently uses it somehow.


Elide logo

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


Star History Chart

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.