Allow Tooling API clients to invoke `--help` and `--version` #35987

usv240 · 2025-12-10T00:28:27Z

Context

This PR implements support for --help, --version, and --show-version command-line arguments in the Tooling API.

Previously, providing these arguments via longRunningOperation.withArguments(...) would often fail (e.g., "Task not found" errors) or be ignored because the Tooling API treated the request as a standard build execution rather than a meta-information request.

Implementation Details:

Introduced VersionHelpConsumerActionExecutor to the connection chain.
The executor intercepts execution if --help, --version, or --show-version are detected.
It explicitly clears tasks and arguments to prevent build failures.
It queries the Help model (for --help) or BuildEnvironment model (for --version) to generate the correct output.
For --show-version, it prints the version information and then proceeds with the original build action.

Contributor Checklist

Review Contribution Guidelines.
Make sure that all commits are signed off to indicate that you agree to the terms of Developer Certificate of Origin.
Make sure all contributed code can be distributed under the terms of the Apache License 2.0, e.g. the code was written by yourself or the original code is licensed under a license compatible to Apache License 2.0.
Check "Allow edit from maintainers" option in pull request so that additional changes can be pushed by Gradle team.
Provide integration tests (under <subproject>/src/integTest) to verify changes from a user perspective.
Provide unit tests (under <subproject>/src/test) to verify logic.
Update User Guide, DSL Reference, and Javadoc for public-facing changes.
Ensure that tests pass sanity check: ./gradlew sanityCheck.
Ensure that tests pass locally: ./gradlew :tooling-api:quickTest.

…rsion Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

Copilot

Pull request overview

This PR implements support for --help, --version, and --show-version command-line arguments in the Tooling API by introducing a VersionHelpConsumerActionExecutor that intercepts these flags and handles them appropriately before build execution.

Key Changes:

Introduced VersionHelpConsumerActionExecutor to handle help and version flags in the Tooling API execution chain
Added getConnectionParameters() method to ConsumerOperationParameters for parameter access
Updated test preconditions from GradleBuildJvmSpecAvailable to Jdk17Available for consistency

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`platforms/ide/tooling-api/src/main/java/org/gradle/tooling/internal/consumer/connection/VersionHelpConsumerActionExecutor.java`	New executor that intercepts `--help`, `--version`, and `--show-version` arguments and handles them by querying Help or BuildEnvironment models
`platforms/ide/tooling-api/src/main/java/org/gradle/tooling/internal/consumer/ConnectionFactory.java`	Integrates the new `VersionHelpConsumerActionExecutor` into the connection chain
`platforms/ide/tooling-api/src/main/java/org/gradle/tooling/internal/consumer/parameters/ConsumerOperationParameters.java`	Adds getter method for accessing connection parameters
`platforms/ide/tooling-api/src/test/groovy/org/gradle/tooling/internal/consumer/connection/VersionHelpConsumerActionExecutorTest.groovy`	Unit tests for the new executor covering delegation, help output, version output, and show-version scenarios
`platforms/ide/tooling-api/src/crossVersionTest/groovy/org/gradle/integtests/tooling/r940/VersionHelpConsumerCrossVersionSpec.groovy`	Cross-version integration tests verifying behavior across Gradle versions
`testing/smoke-test/src/smokeTest/groovy/org/gradle/smoketests/GradleBuildToolingApiSmokeTest.groovy`	Smoke tests validating the functionality in real-world scenarios
`testing/smoke-test/src/smokeTest/groovy/org/gradle/smoketests/AbstractGradleceptionSmokeTest.groovy`	Updates test precondition and fixes path separator handling for Windows compatibility
`testing/smoke-test/src/testFixtures/groovy/org/gradle/test/preconditions/SmokeTestPreconditions.groovy`	Adds new `Jdk17Available` precondition for smoke tests
`testing/internal-testing/src/main/resources/valid-precondition-combinations.csv`	Registers the new precondition combination as valid

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ljacomet · 2025-12-11T13:51:06Z

Thank you for your proposed contribution!

This PR has a valid DCO and tests. The relevant team for this area will confirm the design of the implementation choices.

@usv240 Even before the team looks at this, could you make sure that ./gradlew sanityCheck passes? You can see a failure in the reported results.

Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

donat · 2025-12-16T10:52:47Z

@bot-gradle test ACT

bot-gradle · 2025-12-16T12:23:05Z

The following builds have passed:

All Cross-Version Tests for Ready for Release (Trigger) (Ready for Release)
- Build Scan

donat · 2025-12-17T10:52:58Z

...ionTest/groovy/org/gradle/integtests/tooling/r940/VersionHelpConsumerCrossVersionSpec.groovy

+
+@ToolingApiVersion(">=9.4.0")
+@TargetGradleVersion(">=9.4.0")
+class VersionHelpConsumerCrossVersionSpec extends ToolingApiSpecification {


❌ Please separate the coverage for help and version-related coverage intoto two related test classes.

donat · 2025-12-17T10:53:36Z

...ionTest/groovy/org/gradle/integtests/tooling/r940/VersionHelpConsumerCrossVersionSpec.groovy

+@TargetGradleVersion(">=9.4.0")
+class VersionHelpConsumerCrossVersionSpec extends ToolingApiSpecification {
+
+    def "prints version info and ignores tasks when --version is present"() {


❌ Missing test coverage for old target Gradle versions.

donat · 2025-12-17T10:54:17Z

...ionTest/groovy/org/gradle/integtests/tooling/r940/VersionHelpConsumerCrossVersionSpec.groovy

+class VersionHelpConsumerCrossVersionSpec extends ToolingApiSpecification {
+
+    def "prints version info and ignores tasks when --version is present"() {
+        def output = new ByteArrayOutputStream()


There's an existing result.output property available in this class. You can define assertions on that.

donat · 2025-12-17T11:05:43Z

.../java/org/gradle/tooling/internal/consumer/connection/VersionHelpConsumerActionExecutor.java

+import java.util.Collections;
+import java.util.List;
+
+public class VersionHelpConsumerActionExecutor implements ConsumerActionExecutor {


❌ Although this kind of works, I find it quite hack-ish. I've spent quite some time and looked into the details. The main problem is that this ActionExecutor intercepts the TAPI requests at the wrong abstraction level: outside of where the project connection is available.

The main issue is that here we don't know anything about the provider side (ie the target Gradle distribution). Currently it seems sufficient that we simply catch the exception when an unsupported Gradle version is being used. At the same time, the plan is to backport the --help and the --version rendering for older Gradle versions that is impossible here.

I propose the following: move the interception logic into org.gradle.tooling.internal.consumer.connection.AbstractConsumerConnection.

Maybe extract the interception logic to a subclass between AbstractConsumerConnection and it's existing immediate subclass.

There, you have access to VersionDetails which you can use to separate the supported/unsupported cases.

You can do the interceptions only for task execution.

For model loading, launching tests you could look into how to improve existing functionality

Don't fail model loading/test execution when --help or --version is listed as arguments

Instead emit a warning that the argument list was cleaned up.

Later (in a separate PR) we can add static content for older Gradle versions in the new ConsumerConnection class.

donat · 2025-12-17T11:06:28Z

testing/internal-testing/src/main/resources/valid-precondition-combinations.csv

 IntegTestPreconditions$Java21HomeAvailable,IntegTestPreconditions$Java17HomeAvailable,IntegTestPreconditions$NotEmbeddedExecutor
 UnitTestPreconditions$NotAlpine
 UnitTestPreconditions$NotWindows,UnitTestPreconditions$NotAlpine
+SmokeTestPreconditions$Jdk17Available,UnitTestPreconditions$Jdk9OrLater,IntegTestPreconditions$NotConfigCached


🤔 Seems unrelated

donat · 2025-12-17T11:07:03Z

.../smoke-test/src/smokeTest/groovy/org/gradle/smoketests/GradleBuildToolingApiSmokeTest.groovy

        ].combinations()
    }
+
+    def "can run with --version"() {


❌ We probably don't need this. The cross-version coverage is quite enough.

donat · 2025-12-17T11:07:17Z

...oke-test/src/testFixtures/groovy/org/gradle/test/preconditions/SmokeTestPreconditions.groovy


 class SmokeTestPreconditions {

+    static class Jdk17Available implements TestPrecondition {


Same as above.

…nection and split tests Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

usv240 · 2025-12-18T17:11:44Z

Hi @donat ,
Thanks for the review. I’ve addressed the requested changes and updated the implementation and tests accordingly. Please let me know if anything else needs adjustment.

donat

I'm confused now. The last commit on this PR removed the behavior that we expect:

If the user runs the build with --help or --version the tasks should be ignored and the corresponding help or version info should be printed on the console.

Please restore that behavior.

@donat

- Added handleHelpOrVersion() to intercept flags for task execution - Removed flags with warning for model/test operations - Implemented help precedence over version flags - Fixed entry point requirement in model parameter builder - Updated tests with correct expectations and precedence coverage Addresses review feedback from @donat. Fixes gradle#14116 Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

usv240 · 2025-12-24T01:15:57Z

Hi @donat
Sorry about the confusion! My previous commit was incomplete - I only removed the arguments without actually handling them.

Fixed now with the complete implementation. All your feedback has been addressed.

usv240 requested review from a team as code owners December 10, 2025 00:28

usv240 requested review from Copilot and h0tk3y December 10, 2025 00:28

bot-gradle added from:contributor PR by an external contributor to-triage labels Dec 10, 2025

Copilot started reviewing on behalf of usv240 December 10, 2025 00:29 View session

usv240 added 3 commits December 9, 2025 19:29

Implement VersionHelpConsumerActionExecutor to handle --help and --ve…

71036e5

…rsion Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

Add unit and integration tests for VersionHelpConsumerActionExecutor

bbe7929

Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

Add smoke tests for TAPI CLI help/version support

69eba30

Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

usv240 force-pushed the fix/14116-tapi-cli-help branch from 1c0baeb to 69eba30 Compare December 10, 2025 00:29

Copilot AI reviewed Dec 10, 2025

View reviewed changes

cobexer removed the request for review from a team December 10, 2025 10:30

ljacomet added in:tooling-api 👋 team-triage Issues that need to be triaged by a specific team and removed to-triage labels Dec 11, 2025

Fix CodeNarc violations in smoke tests

036e542

Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

jbartok assigned donat Dec 16, 2025

jbartok removed the 👋 team-triage Issues that need to be triaged by a specific team label Dec 16, 2025

This comment has been minimized.

Sign in to view

donat requested changes Dec 17, 2025

View reviewed changes

donat changed the title ~~Fix/14116 tapi cli help~~ Allow Tooling API clients to invoke --help and --version Dec 17, 2025

Address review comments: move CLI interception to AbstractConsumerCon…

83a7631

…nection and split tests Signed-off-by: Ujwal Suresh Vanjare <[email protected]>

usv240 force-pushed the fix/14116-tapi-cli-help branch from e4b3487 to 83a7631 Compare December 17, 2025 22:51

donat self-requested a review December 23, 2025 08:18

donat requested changes Dec 23, 2025

View reviewed changes

usv240 requested a review from donat December 24, 2025 03:01


		class SmokeTestPreconditions {

		static class Jdk17Available implements TestPrecondition {

Allow Tooling API clients to invoke --help and --version #35987

Are you sure you want to change the base?

Allow Tooling API clients to invoke --help and --version #35987

Uh oh!

Conversation

usv240 commented Dec 10, 2025

Context

Contributor Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ljacomet commented Dec 11, 2025

Uh oh!

donat commented Dec 16, 2025

Uh oh!

This comment has been minimized.

bot-gradle commented Dec 16, 2025

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

donat Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

usv240 commented Dec 18, 2025

Uh oh!

donat left a comment

Choose a reason for hiding this comment

Uh oh!

usv240 commented Dec 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Allow Tooling API clients to invoke `--help` and `--version` #35987

Allow Tooling API clients to invoke `--help` and `--version` #35987