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)