Clarify what "Gradle installation directory" means for gradlew

[joffrey-bion]

Issue type

Missing information

Problem description

In the list for the order of precedence of Gradle properties, the last location is specified as the Gradle installation directory.

What does it mean when using the Gradle wrapper mechanism in a project? Is there such a location at all in that case? It would be nice for this information to be present in the doc, as I couldn't find it so far.

Context (optional)

No response

Page with the problem

https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties

[jbartok]

Thank you for your interest in Gradle!

This is a valid documentation issue that we will address.

[joffrey-bion]

By the way, as a derived question, how can I specify a default value for the whole machine for a given property (say, org.gradle.java.installations.fromEnv) for all projects (even those using the Gradle wrapper), and that is still overridable on per-project basis? (I cannot use the user home's gradle.properties because it must not have precedence over the project's decision in the project's gradle.properties).

This would be a typical use case for CI runners that provide multiple JDK installations, looping back to:
#14903 (comment)

[asteiner-psh]

Looking at the PR that closed this ticket, I do not see any changes that addresses the reported issue (Clarify what "Gradle installation directory" means for gradlew)

Also, in the PR, this issue is mentioned with an incorrect label: "Fix build order preference - #26088"

Is it possible this issue was incorrectly referenced in that PR?

[lkasso]

Hey @asteiner-psh, the changes aren't public yet.

I updated the two files with this question in mind (note this is still not released on https://docs.gradle.org/current):

• https://docs.gradle.org/nightly/userguide/gradle_wrapper.html
• https://docs.gradle.org/nightly/userguide/build_environment.html?

Gradle and the Gradle wrapper use the same order preference.

Is there something I did not answer for you and @joffrey-bion? Please let me know so I can make further updates.

[joffrey-bion]

From the new formulation, it seems that we don't actually need a Gradle installation in the directory that GRADLE_HOME points to. Is this true?

If I create a /gradle_defaults/gradle.properties file with some properties, and set GRADLE_HOME=/gradle_defaults (where /gradle_defaults does not contain a gradle installation), will it be used in prio order 3.2 by projects using the wrapper?

If yes, this mean I could use it to define default properties that can be overriden on a per-project basis.

[lkasso]

@joffrey-bion, Gradle will automatically store all downloaded versions of Gradle in GRADLE_USER_HOME. That way, as you switch Gradle versions in your projects, you don't have to download a fresh copy.

This is not to be confused with GRADLE_HOME.

The GRADLE_HOME is entirely optionally and very rarely used. It cannot be used with Gradle Wrapper.
When GRADLE_HOME is used, it is to specify a local Gradle version.

this mean I could use it to define default properties that can be overriden on a per-project basis.

What you want to do is put your gradle.properties file in GRADLE_USER_HOME, not GRADLE_HOME.

@asteiner-psh, Gradle and the Wrapper don't use GRADLE_HOME.

[joffrey-bion]

this mean I could use it to define default properties that can be overriden on a per-project basis

What you want to do is put your gradle.properties file in GRADLE_USER_HOME, not GRADLE_HOME.

No, GRADLE_USER_HOME doesn't work for me, because properties defined there would override properties from the project's gradle.properties. I want the opposite: I want to specify some default properties for my machine, but still let the project's gradle.properties override them as needed.

The only place to do that in the list is the GRADLE_HOME, not the GRADLE_USER_HOME.

Gradle and the Wrapper don't use GRADLE_HOME.

What do you mean? Then why is this part of the list of places where gradle.properties are searched?

You said Gradle and the Gradle wrapper use the same order preference. If this is true, then the Gradle Wrapper should also look at GRADLE_HOME. If this is not the case, it needs to be made very clear in the table IMO.

[joffrey-bion]

Also, I think it would be rather important not to conflate the types of properties and the mechanisms to set them. It is irrelevant to consider the precedence between 2 different properties. We should see 3 independent tables of priorities: one for system properties, one for gradle properties, one for project properties. And in each table, list all mechanisms to set such properties (which will be similar but not the same).

I expanded much more in the Precedence section in this issue: #26107