Full control over all options given to Java tools

[desruisseaux]

Expected Behavior

When getting a list of compiler arguments with CompileOptions.getCompilerArgs() or StandardJavadocDocletOptions, we can add, remove or edit the arguments to be given to javac or javadoc. We would expect our arguments to be given verbatim to the Java tools, modulo semantic differences between getCompilerArgs() and getAllCompilerArgs(), with no modification added by Gradle after our own modifications. We would also expect to be able to modify all arguments, i.e. the list returned by getAllCompilerArgs().

Current Behavior (optional)

Currently the CompilerOptions class has a getCompilerArgs() method providing a mutable list, but that list is only for additional options appended after the options managed by Gradle. Attempts to modify the options for fixing the class-path versus module-path issue #25954 do not work fully as expected because:

• Adding the --module-path in the compiler options cause the option to appear twice in the debug output of Gradle 8.2. The two occurrences have the exact same path, which may be large. We found no way to prevent that duplication, as it does not appear in the list returned by CompilerOptions.getCompilerArgs().
• --source-path and --module-source-path options are mutually exclusive. But Gradle's debug output seems to unconditionally provide the --source-path option at least with an empty string, because the empty string has a different meaning than the default value. Using the Gradle API for setting the source path to null does not help because Gradle interprets that as an empty path. We saw no API for telling Gradle to omit completely that option. This is a problem because the --module-source-path option is absolutely necessary for Module Source Hierarchy, and Gradle insistence to add its own options causes javac to emit the following: error: cannot specify both --source-path and --module-source-path.
• In the Javadoc task, we cannot set the class-path versus module-path correctly because the class-path is modified again by Gradle after we configured StandardJavadocDocletOptions. The class-path was incomplete at the time we wanted to configure the options, and is magically completed later with undesired new entries added after we have set the value that we wanted. This behavior causes Javadoc generation to fail in a Module Source Hierarchy, with no workaround we could find so far.

I think that in some cases, developers need a way to have the final word on all options to be given to Java tools (except the list of source files to compile), with the guarantee that the list contains all options that Gradle wanted to provide (no missing class-path entries magically added later), and that Gradle will not apply any further modification to this list. The wish is to avoid any "clever" attempt by Gradle to "help" users with options that Gradle thinks should be added. I saw that there is a CompilerOptions.getAllCompilerArgs() method, but unfortunately the returned list is unmodifiable.

The reason why full control on all compiler options is sometime desired is because latest Java releases may have new features that are incompatible with the options managed by Gradle. Above issue with --source-path versus --module-source-path is an example. Even if Gradle resolves this incompatibility, other incompatibles options existed in the past (e.g. -release versus -source and -target) and we cannot know in advance what will be the next incompatible options in future Java releases. We may also want to do cleanups such as removing the --module-path duplication.

Context

This issue is part of an effort to migrate the Apache SIS project from Maven to Gradle in order to support Module Source Hierarchy. What is Module Source Hierarchy, and how it worked with Gradle so far, are described in the following document:

• Java Module Source Hierarchy in a Gradle sub-project

The most critical issue is #25954, but the wish expressed in this issue would be a helpful fallback when a standard Java feature is not yet well supported by Gradle.

[ov7a]

Thank you for your interest in Gradle!

This issue needs a decision from the team responsible for that area. They have been informed. Response time may vary.

[big-guy]

We're not sure that providing an escape hatch that would allow complete control over the arguments passed to underlying tools (compiler, javadoc, etc) is a good general solution. Our concern is that this would introduce new problems and break some underlying assumptions that make up-to-date checking, incremental compilation, etc work.

There's no easy workaround here short of re-implementing a Java-like plugin or disabling all of our optimizations to run javac directly (as one example).

We think the proper fix for some of the issues raised here is to more deeply integrate JPMS/module system support into the existing Java plugins.