From 9030225fb3751f62fefe7b63f0ae859fc83fceef Mon Sep 17 00:00:00 2001
From: Sam Gammon <sam@elide.ventures>
Date: Wed, 16 Aug 2023 20:22:06 -0700
Subject: [PATCH] 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              |  1 +
 docs/binary-targets.md | 28 ++++++++++++++++++++++++++++
 docs/index.md          |  1 +
 3 files changed, 30 insertions(+)
 create mode 100644 docs/binary-targets.md

diff --git a/README.md b/README.md
index 37400a08..1d1b156a 100644
--- a/README.md
+++ b/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)
 
diff --git a/docs/binary-targets.md b/docs/binary-targets.md
new file mode 100644
index 00000000..01e4b0d0
--- /dev/null
+++ b/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)
+```
diff --git a/docs/index.md b/docs/index.md
index 949fe3bb..436fdb65 100644
--- a/docs/index.md
+++ b/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)