Documentation and System Properties

Bugs
1

The documentation from Chapter 20.1 of the user guide states that properties (even system properties) are assigned as:

  • from project gradle.properties file
  • from user gradle.properties file
  • from command line (and even uses -D reference)

There is an open issue regarding this behavior:

https://issues.gradle.org/browse/GRADLE-2122

I threw together a quick example of how it is a bit confusing, as command line System properties under most circumstances appear to do what is desired (as with the daemon), but under others where reading the property is deferred to later are not (deamon starts sometimes but always read as false from build file):

Should the user documentation be adjusted to explain that it depends upon when the read operation of the system property occurs as to which value will be actually used/seen?

-Spencer

2

Thanks Spencer. My guess is that “At some point after starting a JVM instance” is the point at which we start the daemon. So using the ‘org.gradle.daemon.enabled’ property is a bit problematic for experiments.

There are certainly exceptions to our passing of system properties to the daemon JVM: https://github.com/gradle/gradle/blob/master/subprojects/launcher/src/integTest/groovy/org/gradle/launcher/daemon/DaemonSystemPropertiesIntegrationTest.groovy#L22-22.

I would be very interested in an outline of any other cases where we are not honouring our documented behaviour. We should document these particular exceptions, and possibly explicitly warn about our ignoring them.

3

I guess I should not have used the daemon system property as a reference, since this happens to system properties with or without the daemon running.
It seems that all system properties specified on the command line eventually get overridden by values found in either the root gradle.properties file or the user’s gradle.properties file.
In some environments it is common to need client certificates to access certain resources, and setting the information in a user’s gradle.properties file. Unfortunately, right now, it means those values cannot be overridden on the command line if necessary, because by the time the first SSL Socket is requested, the values have already been set to what’s in the gradle.properties files.

javax.net.ssl.keyStorejavax.net.ssl.keyStorePassword
Not sure if you ran the gradle-sysprop-test I referenced, but it demonstrates this behavior.

4

You’re right, this is unfortunate behaviour. The documentation is referring to how to set particular Gradle build environment properties, like ‘org.gradle.daemon’ and ‘org.gradle.parallel’. Note that these properties can be set in a variety of ways, including by setting a matching system property.

For the setting of system properties via the various mechanisms, I don’t think the documentation is clear enough. I also think it would be better behaviour if setting a system property via -Dfoo=bar could override a systemProp.foo=bar setting. I’ve updated the Jira issue title to more clearly describe the problem.

If you want to take this further, I would suggest
a) A pull request to improve the user guide to describe the current behaviour (avoiding the use of ‘org.gradle’ examples, which confuse things)
b) Raise a discussion on the dev list about if/how this should be fixed.

Thanks, Daz