Document JDK selection with --java_toolchain and --javabase flags.
This is a common user journey, and I'm surprised that we don't have this documented anywhere.
https://stackoverflow.com/questions/59040291/configuring-bazel-to-build-test-using-a-specific-jvm-version
https://stackoverflow.com/questions/59761069/changing-java-version-in-bazel
https://stackoverflow.com/questions/59021153/bazel-with-java-11-on-ubuntu
RELNOTES:
PiperOrigin-RevId: 310679726
diff --git a/site/docs/bazel-and-java.md b/site/docs/bazel-and-java.md
index 60f0db4..d8113cd 100644
--- a/site/docs/bazel-and-java.md
+++ b/site/docs/bazel-and-java.md
@@ -95,3 +95,79 @@
* [`java`](skylark/lib/JavaSkylarkApiProvider.html)
* [`JavaInfo`](skylark/lib/JavaInfo.html)
+
+## Configuring the JDK
+
+Bazel is configured to use a default OpenJDK 11 for building and testing
+JVM-based projects. However, you can switch to another JDK using the
+[`--java_toolchain`](command-line-reference.html#flag--java_toolchain) and
+[`--javabase`](command-line-reference.html#flag--javabase) flags.
+
+In short,
+
+* `--java_toolchain`: A [`java_toolchain`](be/java.html#java_toolchain)
+ target that defines the set of Java tools for building target binaries.
+* `--javabase`: A [`java_runtime`](be/java.html#java_runtime) target defining
+ the Java runtime for running target JVM binaries.
+
+The
+[`--host_java_toolchain`](command-line-reference.html#flag--host_java_toolchain)
+and [`--host_javabase`](command-line-reference.html#flag--host_javabase)
+variants are meant for building and running host binaries that Bazel
+uses for building target binaries. These host binaries belong to
+`--java_toolchain`, which includes `JavaBuilder` and `Turbine`.
+
+Bazel's default flags essentially look like this:
+
+```
+$ bazel build \
+ --host_javabase=@bazel_tools//tools/jdk:remote_jdk11 \
+ --javabase=@bazel_tools//tools/jdk:remote_jdk11 \
+ --host_java_toolchain=@bazel_tools//tools/jdk:toolchain_java11 \
+ --java_toolchain=@bazel_tools//tools/jdk:toolchain_java11 \
+ //my/java:target
+```
+
+`@bazel_tools` comes with a number of `java_toolchain` targets. Run the
+following command to list them:
+
+```
+$ bazel query 'kind(java_toolchain, @bazel_tools//tools/jdk:all)'
+```
+
+Similarly for `java_runtime` targets:
+
+```
+$ bazel query 'kind(java_runtime, @bazel_tools//tools/jdk:all)'
+```
+
+For example, if you'd like to use a locally installed JDK installed at
+`/usr/lib/jvm/java-13-openjdk`, use the `absolute_javabase` `java_runtime`
+target and the `toolchain_vanilla` `java_toolchain` target, and define
+`ABSOLUTE_JAVABASE` as the absolute path to the JDK.
+
+
+```
+bazel build \
+ --define=ABSOLUTE_JAVABASE=/usr/lib/jvm/java-13-openjdk \
+ --javabase=@bazel_tools//tools/jdk:absolute_javabase \
+ --host_javabase=@bazel_tools//tools/jdk:absolute_javabase \
+ --java_toolchain=@bazel_tools//tools/jdk:toolchain_vanilla \
+ --host_java_toolchain=@bazel_tools//tools/jdk:toolchain_vanilla \
+ //my/java_13:target
+```
+
+Optionally, you can add the flags into your project's `.bazelrc` file to
+avoid having to specify them every time:
+
+```
+build --define=ABSOLUTE_JAVABASE=/usr/lib/jvm/java-13-openjdk
+build --javabase=@bazel_tools//tools/jdk:absolute_javabase
+build --host_javabase=@bazel_tools//tools/jdk:absolute_javabase
+build --java_toolchain=@bazel_tools//tools/jdk:toolchain_vanilla
+build --host_java_toolchain=@bazel_tools//tools/jdk:toolchain_vanilla
+```
+
+You can also write your own `java_runtime` and `java_toolchain` targets. As a
+tip, use `bazel query --output=build @bazel_tools//tools/jdk:all` to see how
+the built-in runtime and toolchain targets are defined.
