rules_elide is a Bazel module with Java and Kotlin rules that compile through elide javac and elide kotlinc
running as persistent workers, plus rules for Javadoc, JARs, bytecode reports, C bindings, KAPT/KSP and native
images. It downloads a pinned Elide release; no Kotlin compiler is needed. It can also replace the builder of
existing kt_jvm_* targets and run py_binary and py_test targets on Elide’s Python.
Requirements
| Version | |
|---|---|
| Bazel | 8 or later, with Bzlmod |
rules_elide |
0.7.0 |
| Elide | 1.6.2 (the default) |
| Platforms | Linux x86_64 and arm64, macOS arm64 |
rules_kotlin |
2.4.21, for kt_jvm_* targets |
rules_python |
1.7.0, for Python targets |
ABI headers, KAPT/KSP rules, compiler dependency reports and the native kt_jvm_* builder need Elide 1.6.2.
Install
# MODULE.bazel
bazel_dep(name = "rules_elide", version = "0.7.0")
elide = use_extension("@rules_elide//elide:extensions.bzl", "elide")
elide.install(version = "1.6.2")
use_repo(elide, "elide_toolchains")
register_toolchains("@elide_toolchains//:all")
elide.install() downloads Elide from GitHub releases for each supported platform and checks each archive against a
hash pinned in the module. MODULE.bazel.lock records the result. When several modules call it, the highest
version wins.
| Attribute | Use |
|---|---|
version |
A pinned version (below); default 1.6.2 |
python |
Also install the matching Python overlay |
url_template |
Mirror URL with {version}, {os}, {cpu}, {ext} |
python_url_template |
Mirror URL for the Python overlay |
repo_prefix |
Per-platform repository prefix; default elide |
Pinned versions: 1.6.0, 1.6.1, 1.6.2, the nightlies 1.6.2+20261102 and 1.6.2+20261103, and older 1.2 to 1.4
nightlies. Each platform’s distribution is also a repository, such as @elide_linux_amd64, whose //:bin/elide
label the Kotlin and Python toolchain macros take; add it to use_repo when you need it.
To use any other Elide, such as 1.6.3 or a local build, elide.use in the root module replaces elide.install:
elide.use(local_path = "/opt/elide")
local_path serves only the host platform and makes the build non-reproducible. For a downloaded release, pass
version, url_template and integrity, a map from linux_amd64-style keys to SRI hashes; only the listed
platforms get a toolchain:
elide.use(
version = "1.6.3",
url_template = "https://github.com/elide-dev/elide/releases/download/v{version}/elide.{os}-{cpu}.{ext}",
integrity = {"linux_amd64": "sha256-..."},
)
Rules
Load from @rules_elide//elide:defs.bzl.
| Rule | Does |
|---|---|
elide_java_library |
Compiles .java sources into a JAR |
elide_java_binary |
Library plus a launcher (bazel run) |
elide_java_test |
Library plus a JUnit Platform launcher (bazel test) |
elide_kotlin_library |
Compiles .kt and mixed .kt/.java sources |
elide_kotlin_binary, elide_kotlin_test |
As the Java variants, for Kotlin |
elide_format |
bazel run target that formats sources in place |
elide_native_image |
Native executable from JVM targets |
elide_javadoc |
Javadoc HTML and a -javadoc.jar |
elide_jar |
Reproducible JAR from files |
elide_jdeps, elide_javap |
Dependency or bytecode report (.txt) |
elide_jextract |
Java bindings (.srcjar) for C headers |
elide_kapt, elide_ksp |
Processor output (.srcjar) |
elide_toolchain |
Wraps an elide binary as a toolchain |
Common attributes of the compile rules:
| Attribute | Use |
|---|---|
srcs, deps, runtime_deps, exports |
As in java_library |
resources, resource_jars |
Files and JARs packed into the output |
plugins |
Compiler plugins and annotation processors |
javac_opts |
javac flags (via kotlinc in Kotlin rules) |
kotlinc_opts, module_name |
kotlinc flags and module name |
associates |
Kotlin friend targets (internal access) |
builtin_plugins |
serialization, metro, atomicfu, power-assert |
main_class, jvm_flags |
Binaries and tests |
test_class |
One test class; empty scans the classpath |
Every compile rule returns JavaInfo with the full JAR, a compile JAR (ijar, or an ABI header when enabled) and a
source JAR, so java_library, kt_jvm_library and rules_jvm_external targets mix freely in deps.
Test rules run the JUnit Platform console launcher under elide java and need
org.junit.platform:junit-platform-console-standalone in runtime_deps. They honor --test_filter and write
Bazel’s XML report. JAVA_HOME comes from Bazel’s current Java runtime; if local JDK detection fails, set
--java_runtime_version=remotejdk_21.
elide_format runs google-java-format on .java sources and ktfmt on .kt/.kts, one language per target:
bazel run //:format
The JVM tool rules run the matching elide command (JAR assembly,
C header bindings):
elide_javadoc(name = "api_docs", srcs = glob(["src/**/*.java"]), deps = [":greeter"])
elide_javap(name = "bytecode", classes = ["Greeter"], opts = ["-c"], deps = [":greeter"])
elide_jextract(name = "bindings", srcs = ["include/api.h"], hdrs = ["include/types.h"], package = "demo.ffi")
elide_kapt and elide_ksp take srcs, deps, processor_deps or processor_jars, and processor_options;
processors (class names) applies to KAPT only, since KSP discovers SymbolProcessorProvider services. Their output
groups generated_sources, generated_classes and stubs feed rules_java or rules_kotlin targets.
elide_native_image takes deps, main_class and native_image_opts. It needs a GraalVM JDK: set
--@rules_elide//elide:graalvm_home=<path>, or export JAVA_HOME and add --action_env=JAVA_HOME.
See Native Image.
Opt-in compile settings, each prefixed with --@rules_elide//:
| Setting | Effect |
|---|---|
config/ |
Java compile JARs from ABI headers |
config/ |
The same for Kotlin and mixed targets |
elide:emit_jdeps=true |
.jdeps reports, output group jdeps |
elide:prune_ |
Unused classpath entries skip rebuilds |
With ABI headers, a change to a method body leaves the header unchanged and dependents are not recompiled. Pruning
reports go to output group unused_inputs and are off for targets with plugins, processors or incremental compiles.
Full attribute reference: rules_elide docs.
Example
MODULE.bazel
BUILD.bazel
src/Greeter.java
src/App.kt
src/GreeterTest.java
# MODULE.bazel
module(name = "hello")
bazel_dep(name = "rules_elide", version = "0.7.0")
bazel_dep(name = "rules_jvm_external", version = "7.2")
elide = use_extension("@rules_elide//elide:extensions.bzl", "elide")
elide.install(version = "1.6.2")
use_repo(elide, "elide_toolchains")
register_toolchains("@elide_toolchains//:all")
maven = use_extension("@rules_jvm_external//:extensions.bzl", "maven")
maven.install(
artifacts = [
"org.junit.jupiter:junit-jupiter-api:5.13.4",
"org.junit.platform:junit-platform-console-standalone:1.13.4",
],
)
use_repo(maven, "maven")
# BUILD.bazel
load("@rules_elide//elide:defs.bzl", "elide_format", "elide_java_library", "elide_java_test", "elide_kotlin_binary")
elide_java_library(
name = "greeter",
srcs = ["src/Greeter.java"],
)
elide_kotlin_binary(
name = "app",
srcs = ["src/App.kt"],
main_class = "AppKt",
deps = [":greeter"],
)
elide_java_test(
name = "greeter_test",
srcs = ["src/GreeterTest.java"],
test_class = "GreeterTest",
runtime_deps = ["@maven//:org_junit_platform_junit_platform_console_standalone"],
deps = [
":greeter",
"@maven//:org_junit_jupiter_junit_jupiter_api",
],
)
elide_format(
name = "format",
srcs = glob(["src/*.java"]),
)
bazel build //...
bazel run //:app
bazel test //:greeter_test
Hello, Bazel
//:greeter_test PASSED in 2.0s
Executed 1 out of 1 test: 1 test passes.
Persistent workers
The compile rules run elide javac --persistent_worker and elide kotlinc --persistent_worker as multiplex workers:
one warm process per tool serves every compile action. bazel shutdown stops them. Worker settings, each prefixed
with --@rules_elide//:
| Setting | Effect |
|---|---|
elide:use_workers=false |
A new process per compile action |
config/ |
Reuse parsed classpath JARs |
config/ |
Incremental Kotlin compiles (experimental) |
Turn workers off for remote execution:
bazel build --@rules_elide//elide:use_workers=false //...
The incremental cache survives between requests only in unsandboxed workers; under --worker_sandboxing or remote
execution each compile starts cold.
Workers from your own rules
Without rules_elide, any rule can run Elide as a worker. Bazel adds --persistent_worker itself; the rule passes
arguments in a parameter file:
# elide.bzl
def _elide_javac_impl(ctx):
out = ctx.actions.declare_directory(ctx.label.name + "_classes")
args = ctx.actions.args()
args.add("-d", out.path)
args.add_all(ctx.files.srcs)
args.use_param_file("@%s", use_always = True)
args.set_param_file_format("multiline")
ctx.actions.run(
executable = ctx.executable._elide,
arguments = ["javac", args],
inputs = ctx.files.srcs,
outputs = [out],
mnemonic = "ElideJavac",
execution_requirements = {"supports-workers": "1", "supports-multiplex-workers": "1"},
)
return [DefaultInfo(files = depset([out]))]
elide_javac = rule(
implementation = _elide_javac_impl,
attrs = {
"srcs": attr.label_list(allow_files = [".java"]),
"_elide": attr.label(default = "//tools:elide", executable = True, cfg = "exec", allow_single_file = True),
},
)
# BUILD.bazel
load(":elide.bzl", "elide_javac")
elide_javac(
name = "hello",
srcs = glob(["src/*.java"]),
)
mkdir -p tools && ln -s "$(command -v elide)" tools/elide
echo 'exports_files(["elide"])' > tools/BUILD.bazel
bazel build //:hello
Target //:hello up-to-date:
bazel-bin/hello_classes
INFO: 2 processes: 1 internal, 1 worker.
For javac, pass ["javac", "--classpath-cache", args] to reuse parsed classpath JARs between requests. A kotlinc
rule takes the same form, without --classpath-cache.
With rules_elide installed, a rule can take the binary from the toolchain instead: add
@rules_elide//elide:toolchain_type to toolchains and read ctx.toolchains[...].elide_info.binary, with
compile_tool_files (or python_tool_files) as action inputs.
Keep kt_jvm_* targets
register_elide_kotlin_toolchain wraps a rules_kotlin toolchain and replaces its builder, so existing
kt_jvm_library, kt_jvm_binary and kt_jvm_test targets compile with Elide without BUILD changes:
# MODULE.bazel
bazel_dep(name = "rules_kotlin", version = "2.4.21")
use_repo(elide, "elide_linux_amd64", "elide_toolchains")
register_toolchains("@elide_toolchains//:all")
register_toolchains("//:elide_kt")
# BUILD.bazel
load("@rules_elide//elide/kotlin:toolchain.bzl", "register_elide_kotlin_toolchain")
register_elide_kotlin_toolchain(
name = "elide_kt",
elide = "@elide_linux_amd64//:bin/elide",
fallback_builder = "@rules_kotlin//src/main/kotlin:build",
language_version = "2.4",
api_version = "2.4",
)
Other arguments (jvm_target, experimental_use_abi_jars, …) pass through to define_kt_toolchain. Set
language_version and api_version to a version Elide’s compiler supports; the rules_kotlin default is too old.
The elide label is per platform: use select() over @elide_<os>_<cpu>//:bin/elide for several.
| Request | Compiled by |
|---|---|
| Kotlin, mixed Kotlin/Java | Elide |
| KAPT | Elide |
| KSP2 | Elide |
| Other processor setups | Stock rules_kotlin workers |
KAPT with custom stub plugins or extra javac options, KSP2 in PSI-resolution mode, and KSP1 fall back to the stock
workers. experimental_use_abi_jars = True writes the ABI jar in the same compile, and strict_kotlin_deps is
checked against Elide’s dependency report. -Xplugin JARs for serialization, power-assert, atomicfu and Metro are
replaced by Elide’s built-in plugins with a warning; --@rules_elide//config/kotlinc:warn_builtin_plugin_rewrite=false
silences it. For Elide before 1.6.2, pass native_tools = False: processors then always use the stock workers.
Details: KotlinBuilder shim.
Python targets
register_elide_python_toolchain makes ordinary py_binary, py_test and py_library targets run on Elide’s
Python 3.13, from the overlay that elide.install(python = True) adds:
# MODULE.bazel
bazel_dep(name = "rules_python", version = "1.7.0")
bazel_dep(name = "platforms", version = "1.1.0")
elide.install(version = "1.6.2", python = True)
use_repo(elide, "elide_linux_amd64", "elide_toolchains")
register_toolchains("//:elide_py")
# BUILD.bazel
load("@rules_elide//elide/python:toolchain.bzl", "register_elide_python_toolchain")
register_elide_python_toolchain(
name = "elide_py",
elide = "@elide_linux_amd64//:bin/elide",
runtime_files = "@elide_linux_amd64//:elide_python_files",
target_compatible_with = ["@platforms//os:linux", "@platforms//cpu:x86_64"],
)
# .bazelrc
build --@rules_python//python/config_settings:python_version=3.13
build --@rules_python//python/config_settings:bootstrap_impl=script
Declare one toolchain per target platform. The toolchain matches only Python 3.13 (or an unset version) and the
script bootstrap starts without a host Python. rules_python still resolves packages; no pip or uv runs in
build actions. Pure-Python sources are supported; native wheels, coverage, precompiled bytecode and zip executables
are not validated. See Python toolchain.
OpenRewrite and dependency queries
For projects with an elide.pkl, see OpenRewrite and
Dependency code index. These commands do not consume Bazel’s JavaInfo or its target
graph, and rules_elide does not add a rewrite or code-index target; elide_jdeps and emit_jdeps report
class-level dependencies only. See the project setup boundary
before using them alongside Bazel.
Limits
- Windows is not supported: the KotlinBuilder and Python launchers need Bash, and nothing is validated on Windows.
elide.installaccepts only the pinned versions; useelide.usefor others, including 1.6.3.- Kotlin compiler plugins from external JARs (the
pluginsattribute ofelide_kotlin_*rules) other than all-open, no-arg, sam-with-receiver, assignment and Lombok fail with a compiler error; usebuiltin_pluginsfor bundled ones. builtin_pluginsadds plugins but does not disable bundled plugins detected from the classpath.elide_kotlin_*rules take source files, not generated source JARs; compile processor output withkt_jvm_*.elide_native_imageuses a GraalVM JDK from the host and is not covered by the integration tests.elide_javadoc(theme = "elide")fails with Elide 1.6.2; use the default theme.elide_jextractruns on the execution platform and does not find a cross-compilation sysroot; bindings need JDK 22 or later.- The Python toolchain is tested on Linux x86_64 only.