incompatible_use_toolchain_resolution_for_java_rules: use toolchain resolution for Java rules

[lberki]

Flag: --incompatible_use_toolchain_resolution_for_java_rules
Available since: 5.0.0
Will be flipped in: 5.0.0
Tracking issue: #4592

Motivation

Currently, Java rules find their Java toolchain and JDK using the --javabase / --java_toolchain / --host_javabase / --host_java_toolchain command line options. This will be changed to use platform-based toolchain resolution so as to be consistent with the rest of Bazel and to support multiple platforms more easily.

Migration notes

For --javabase with old values:

• @local_jdk://jdk
• @remotejdk11_{linux,window,darwin}_{cpu}//:jdk
• @remotejdk14_{linux,window,darwin}//:jdk
• @remotejdk15_{linux,window,darwin}.*//:jdk

Replace the flag with --java_runtime_version={local_jdk,remotejdk_14,remotejdk_15}.

For --java_toolchain with old values:

• @bazel_tools//tools/jdk:toolchain,
• @bazel_tools_hostjdk8,
• @bazel_tools//jdk:legacy_toolchain,
• @bazel_tools//tools/jdk:remote_toolchain,
• @bazel_tools//tools/jdk:toolchain_java_{ver},
• @remote_java_tools_xxx//:toolchain,
• @remote_java_tools_xxx//:toolchain_jdk_11,
• @remote_java_tools_xxx//:toolchain_jdk_14,
• @remote_java_tools_xxx//:toolchain_jdk_15

Replace the flag with --java_language_version={8,...,15}

Migration of more advanced cases

For --javabase=@bazel_tools//tools/jdk:​absolute_javabase, use local_java_repositoy in the WORKSPACE file.

For custom --javabase labels, do the following:

1. replace http_archive with remote_java_repository:

remote_java_repository(
   name = ...
   sha256 = ...
   strip_prefix = ...
   urls = ...
   prefix = "myjdk",
   version = "11",
   exec_compatible_with = ["@platforms//cpu:arm", "@platforms//os:linux"]
)

2. replace the old flag with --java_runtime_version with the specified version or prefix_version value (for example --java_runtime_version=myjdk_11).

For old --java_toolchain values:

• @bazel_tools//tools/jdk:toolchain_vanilla
• @remote_java_tools_xxx//:prebuilt_toolchain
• custom label

1. add custom toolchain definition to a BUILD file (or replace custom target):

default_java_toolchain(
  name = "mytoolchain",
  configuration = "PREBUILT_TOOLCHAIN_CONFIGURATION"
     #or "VANILLA_TOOLCHAIN_CONFIGURATION"
  ...
)

2. register custom toolchain in the WORKSPACE or use configuration flag --extra_toolchains.

RBE migration

1. Update the version of bazel_toolchains.
2. Add following flags to .bazelrc affecting remote configuration:

build:remote --java_runtime_version=rbe_jdk     # Uses JDK installed on docker, configured by bazel_toolchains
build:remote --tool_java_runtime_version=rbe_jdk
build:remote --extra_toolchains=@rbe_ubuntu1804//java:all   # Optional: uses JDK installed on docker to compile 

3. In case the sources are not Java 8, also add:

build --java_language_version=11
build --tool_java_language_version=11

4. Once Bazel 4.1.0 is released and used on RBE Remove --{,host}javabase and --{,host}_javatoolchain flags.

[keith]

@lberki can you add migration notes for this? bazelisk's --migrate hits this and it appears that protobuf fails to build with this flag enabled with 0.25.2:

% bazel build :all --incompatible_use_toolchain_resolution_for_java_rules
INFO: Build option --incompatible_use_toolchain_resolution_for_java_rules has changed, discarding analysis cache.
ERROR: /Users/ksmiley/dev/protobuf/BUILD:636:1: in java_library rule //:protobuf_java: header compilation was requested but it is not supported by the current Java toolchain '@bazel_tools//tools/jdk:dummy_toolchain'; see the java_toolchain.header_compiler attribute
ERROR: Analysis of target '//:java_toolchain' failed; build aborted: Analysis of target '//:protobuf_java' failed; build aborted
INFO: Elapsed time: 0.604s
INFO: 0 processes.
FAILED: Build did NOT complete successfully (0 packages loaded, 2453 targets configured)

[laurentlb]

This flag breaks a lot of downstream projects, migration notes are missing, and the error message is unclear. I'm going to remove the migration flag for now.

[cushon]

This flag breaks a lot of downstream projects, migration notes are missing, and the error message is unclear. I'm going to remove the migration flag for now.

There was some discussion of this in cl/240945826, and my understanding was that this met the policy requirements for adding an --incompatible_* flag. Has the policy changed?

I think the plan is still to add migration notes and push forward on this migration soon.

cc @iirina @hlopko

[hlopko]

Correct, we'll add migration instructions and start migrating soon. First we need to introduce Java constraint settings and values. @iirina is well on top of things.

[iirina]

The following java_toolchain targets are exposed by Bazel:

• @bazel_tools//tools/jdk:toolchain
• @bazel_tools//tools/jdk:toolchain_hostjdk8
• @bazel_tools//tools/jdk:legacy_toolchain
• @bazel_tools//tools/jdk:toolchain_vanilla
• @bazel_tools//tools/jdk:toolchain_java{8, 9, 10, 11}

Everyone using --java_toolchain/--host_java_toolchain pointing at any of these targets have to migrate. I'll come back with migration details for every of these targets.