# Bazel

`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

```python
# 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`:

```python
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:

```python
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:

```bash
bazel run //:format
```

The JVM tool rules run the matching `elide` command ([JAR assembly](/docs/toolchain/jvm/jar),
[C header bindings](/docs/toolchain/native/jextract)):

```python
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](/docs/toolchain/jvm/native-image).

Opt-in compile settings, each prefixed with `--@rules_elide//`:

| Setting | Effect |
| --- | --- |
| `config/javac:abi_compile_avoidance=true` | Java compile JARs from ABI headers |
| `config/kotlinc:abi_compile_avoidance=true` | The same for Kotlin and mixed targets |
| `elide:emit_jdeps=true` | `.jdeps` reports, output group `jdeps` |
| `elide:prune_unused_inputs=true` | 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](https://github.com/elide-dev/rules_elide/tree/v0.7.0/docs).

## Example

```text
MODULE.bazel
BUILD.bazel
src/Greeter.java
src/App.kt
src/GreeterTest.java
```

```python
# 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")
```

```python
# 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"]),
)
```

```bash
bazel build //...
bazel run //:app
bazel test //:greeter_test
```

```terminaloutput
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/javac:classpath_cache=true` | Reuse parsed classpath JARs |
| `config/kotlinc:incremental=true` | Incremental Kotlin compiles (experimental) |

Turn workers off for remote execution:

```bash
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:

```python
# 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),
    },
)
```

```python
# BUILD.bazel
load(":elide.bzl", "elide_javac")

elide_javac(
    name = "hello",
    srcs = glob(["src/*.java"]),
)
```

```bash
mkdir -p tools && ln -s "$(command -v elide)" tools/elide
echo 'exports_files(["elide"])' > tools/BUILD.bazel
bazel build //:hello
```

```text
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:

```python
# 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")
```

```python
# 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](https://github.com/elide-dev/rules_elide/blob/v0.7.0/docs/kotlin_builder.md).

## 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:

```python
# 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")
```

```python
# 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"],
)
```

```text
# .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](/docs/python-toolchain).

## OpenRewrite and dependency queries

For projects with an `elide.pkl`, see [OpenRewrite](/docs/toolchain/jvm/rewrite) and
[Dependency code index](/docs/toolchain/jvm/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](/docs/build-tools#openrewrite-and-dependency-queries)
before using them alongside Bazel.

## Limits

- Windows is not supported: the KotlinBuilder and Python launchers need Bash, and nothing is validated on Windows.
- `elide.install` accepts only the pinned versions; use `elide.use` for others, including 1.6.3.
- Kotlin compiler plugins from external JARs (the `plugins` attribute of `elide_kotlin_*` rules) other than all-open,
  no-arg, sam-with-receiver, assignment, Lombok, Compose, Parcelize and the built-in plugins fail with a compiler
  error; use `builtin_plugins` for bundled ones.
- `builtin_plugins` adds plugins but does not disable bundled plugins detected from the classpath.
- `elide_kotlin_*` rules take source files, not generated source JARs; compile processor output with `kt_jvm_*`.
- `elide_native_image` uses 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_jextract` runs 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.
