docs: add doc for binary targets

- docs: add `binary-targets` doc
- chore: link to new binary targets doc from readme
- chore: link to new binary targets doc from docs index

README.md

@@ -18,6 +18,7 @@ Use [GraalVM](https://graalvm.org) from [Bazel](https://bazel.build), with suppo
 - [Installing components with `gu`](./docs/components.md)
 - [Using GraalVM as a Bazel Java toolchain](./docs/toolchain.md)
 - [Support for Bazel 6, Bazel 7, and Bzlmod](./docs/modern-bazel.md)
+- [Run GraalVM binaries directly](./docs/binary-targets.md)
 - Support for macOS, Linux, Windows (including `native-image`!)
 - Support for latest modern GraalVM releases (Community Edition and Oracle GraalVM)
 

docs/binary-targets.md

@@ -0,0 +1,28 @@
+## Targets for binaries in GraalVM
+
+For convenience, the GraalVM repository rule will create targets and aliases for major binaries which ship with GraalVM. You can use these out of the box.
+
+**Binaries which are typically aliased, based on installed components:**
+
+| Binary | Target | Alias | Example |
+| -------------- | ----------------------------- | ------------------------- | -------------------------------------- |
+| `java` | `@graalvm//:bin/java` | `@graalvm` | `bazel run -- @graalvm` |
+| `javac` | `@graalvm//:bin/javac` | `@graalvm//:javac` | `bazel run -- @graalvm//:javac` |
+| `jar` | `@graalvm//:bin/jar` | `@graalvm//:jar` | `bazel run -- @graalvm//:jar` |
+| `native-image` | `@graalvm//:bin/native-image` | `@graalvm//:native-image` | `bazel run -- @graalvm//:native-image` |
+| `polyglot` | `@graalvm//:bin/polyglot` | `@graalvm//:polyglot` | `bazel run -- @graalvm//:polyglot` |
+| `js` | `@graalvm//:bin/js` | `@graalvm//:js` | `bazel run -- @graalvm//:js` |
+| `wasm` | `@graalvm//:bin/wasm` | `@graalvm//:wasm` | `bazel run -- @graalvm//:wasm` |
+| `python` | `@graalvm//:bin/python` | `@graalvm//:python` | `bazel run -- @graalvm//:python` |
+| `ruby` | `@graalvm//:bin/ruby` | `@graalvm//:ruby` | `bazel run -- @graalvm//:ruby` |
+| `lli` | `@graalvm//:bin/lli` | `@graalvm//:lli` | `bazel run -- @graalvm//:lli` |
+
+**Example:**
+
+```
+$ > b run -- @graalvm --version
+# ...
+java 20.0.2 2023-07-18
+Java(TM) SE Runtime Environment Oracle GraalVM 20.0.2+9.1 (build 20.0.2+9-jvmci-23.0-b14)
+Java HotSpot(TM) 64-Bit Server VM Oracle GraalVM 20.0.2+9.1 (build 20.0.2+9-jvmci-23.0-b14, mixed mode, sharing)
+```

docs/index.md

@@ -8,6 +8,7 @@ These rules let you use [GraalVM](https://graalvm.org) from [Bazel](https://baze
 - [Installing components with `gu`](./components.md)
 - [Using GraalVM as a Bazel Java toolchain](./toolchain.md)
 - [Support for Bazel 6, Bazel 7, and Bzlmod](./modern-bazel.md)
+- [Run GraalVM binaries directly](./binary-targets.md)
 - Support for macOS, Linux, Windows (including `native-image`!)
 - Support for latest modern GraalVM releases (Community Edition and Oracle GraalVM)