Add support for CLIENT_JAVA_HOME (#434)

* Add support for CLIENT_JAVA_HOME

Users can use CLIENT_JAVA_HOME to override which JVM is used to execute the
Build Scan clients.  The other JVMs used (for running Gradle and for building
code) are not affected.

* Update release/changes.md

* Add missing backtick

* Remove extra space

* Fallback to using JAVA_HOME if CLIENT_JAVA_HOME is not set

* Add a section to the READMEs for setting the JVM used to fetch build scan data

* Add newline to separate sections

Co-authored-by: Eric Haag <[email protected]>
Signed-off-by: Jim Hurne <[email protected]>

* Polish docs

* Polish docs some more

* Polish docs some more

* Fix broken anchors

---------

Signed-off-by: Jim Hurne <[email protected]>
Co-authored-by: Eric Haag <[email protected]>
Co-authored-by: Etienne Studer <[email protected]>

Author: 3 people

Gradle.md

@@ -18,7 +18,7 @@ The build validation scripts are compatible with a large range of Gradle version
 
 | Build Validation Scripts version | Compatible Gradle versions | Compatible Gradle Enterprise versions |
 |----------------------------------|----------------------------|---------------------------------------|
-| 2.0+                             | 5.0+                       | 2022.1+                               |  
+| 2.0+                             | 5.0+                       | 2022.1+                               |
 | 1.0 - 1.0.2                      | 5.0+                       | 2021.2+                               |
 
 ## Installation
@@ -86,7 +86,7 @@ is invoked, as shown in the example below.
 
 The scripts return with an exit code that depends on the outcome of running a given experiment.
 
-| Exit Code | Reason                                                                                                 | 
+| Exit Code | Reason                                                                                                 |
 |-----------|--------------------------------------------------------------------------------------------------------|
 | 0         | The experiment completed successfully                                                                  |
 | 1         | An invalid input was provided while attempting to run the experiment                                   |
@@ -150,17 +150,35 @@ Gradle Enterprise server at ge.example.io.
 ./02-validate-local-build-caching-same-location.sh -i -e -s https://ge.example.io
 ```
 
-## Running the experiments without publishing build scans
+## Running the experiments without publishing Build Scan data
 
-The scripts that run all builds locally can be configured to not publish any build scans and instead extract the required data
-right during the build to surface the state of work avoidance by passing the `-x` or `--disable-build-scan-publishing` command 
-line argument. Obviously, no deeper analysis via build scans is possible. The use of this configuration option requires a license
-file from Gradle Inc. to be present in the root directory of the scripts.
+The scripts that run all builds locally can be configured to not publish any Build Scan data and instead extract the required data
+right during the build to surface the state of work avoidance by passing the `-x` or `--disable-build-scan-publishing` command
+line argument.
+
+The use of this option requires at least Java 17 to analyze the build data. The JVM version to analyze the build data is
+[configurable](#specifying-the-jvm-used-to-analyze-the-build-data). You can still run the builds of the experiments with a JVM 
+version lower than Java 17.
+
+The use of this configuration option also requires a license file from Gradle Inc. to be present in the root directory of the scripts.
 
 ```bash
 ./02-validate-local-build-caching-same-location.sh -i -x
 ```
 
+## Specifying the JVM used to analyze the build data
+
+The scripts use a Java-based utility to fetch and analyze the captured build data.
+If you need to run the utility with a different Java Virtual Machine than what is configured by default on your system and used when running your builds,
+then you can set the `CLIENT_JAVA_HOME` environment variable when invoking the scripts:
+
+```bash
+CLIENT_JAVA_HOME="/opt/java/temurin-17.0.7+7" ./02-validate-local-build-caching-same-location.sh -i
+```
+
+If `CLIENT_JAVA_HOME` is not specified, then the utility will use the JVM referenced by the `JAVA_HOME` environment variable.
+If `JAVA_HOME` is not defined, then the utility will use the Java executable found on the system path.
+
 ## Analyzing the results
 
 Once a script has finished running its experiment, a summary of what was run and what the outcome was is printed on

Maven.md

@@ -18,7 +18,7 @@ The build validation scripts are compatible with a large range of Maven versions
 
 | Build Validation Scripts version | Compatible Maven versions | Compatible Gradle Enterprise versions |
 |----------------------------------|---------------------------| ------------------------------------- |
-| 2.0+                             | 3.3.1+                    | 2022.1+                               |  
+| 2.0+                             | 3.3.1+                    | 2022.1+                               |
 | 1.0 - 1.0.2                      | 3.3.1+                    | 2021.2+                               |
 
 ## Installation
@@ -84,7 +84,7 @@ is invoked, as shown in the example below.
 
 The scripts return with an exit code that depends on the outcome of running a given experiment.
 
-| Exit Code | Reason                                                                                                 | 
+| Exit Code | Reason                                                                                                 |
 |-----------|--------------------------------------------------------------------------------------------------------|
 | 0         | The experiment completed successfully                                                                  |
 | 1         | An invalid input was provided while attempting to run the experiment                                   |
@@ -148,17 +148,35 @@ Gradle Enterprise server at ge.example.io.
 ./01-validate-local-build-caching-same-location.sh -i -e -s https://ge.example.io
 ```
 
-## Running the experiments without publishing build scans
+## Running the experiments without publishing Build Scan data
 
-The scripts that run all builds locally can be configured to not publish any build scans and instead extract the required data
-right during the build to surface the state of work avoidance by passing the `-x` or `--disable-build-scan-publishing` command 
-line argument. Obviously, no deeper analysis via build scans is possible. The use of this configuration option requires a license
-file from Gradle Inc. to be present in the root directory of the scripts.
+The scripts that run all builds locally can be configured to not publish any Build Scan data and instead extract the required data
+right during the build to surface the state of work avoidance by passing the `-x` or `--disable-build-scan-publishing` command
+line argument.
+
+The use of this option requires at least Java 17 to analyze the build data. The JVM version to analyze the build data is
+[configurable](#specifying-the-jvm-used-to-analyze-the-build-data). You can still run the builds of the experiments with a JVM
+version lower than Java 17.
+
+The use of this configuration option also requires a license file from Gradle Inc. to be present in the root directory of the scripts.
 
 ```bash
 ./01-validate-local-build-caching-same-location.sh -i -x
 ```
 
+## Specifying the JVM used to analyze the build data
+
+The scripts use a Java-based utility to fetch and analyze the captured build data.
+If you need to run the utility with a different Java Virtual Machine than what is configured by default on your system and used when running your builds,
+then you can set the `CLIENT_JAVA_HOME` environment variable when invoking the scripts:
+
+```bash
+CLIENT_JAVA_HOME="/opt/java/temurin-17.0.7+7" ./01-validate-local-build-caching-same-location.sh -i
+```
+
+If `CLIENT_JAVA_HOME` is not specified, then the utility will use the JVM referenced by the `JAVA_HOME` environment variable.
+If `JAVA_HOME` is not defined, then the utility will use the Java executable found on the system path.
+
 ## Analyzing the results
 
 Once a script has finished running its experiment, a summary of what was run and what the outcome was is printed on

components/fetch-build-scan-data-cmdline-tool/src/main/java/com/gradle/enterprise/cli/FetchBuildScanDataCommand.java

@@ -56,6 +56,7 @@ public static class ExitCode {
     public Integer call() {
         // Use System.err for logging since we're going to write out the CSV to System.out
         logger = new ConsoleLogger(System.err, colorScheme, debug);
+        logger.debug("Using JVM at " + System.getProperty("java.home"));
 
         networkSettingsFile.ifPresent(settingsFile -> NetworkSettingsConfigurator.configureNetworkSettings(settingsFile, logger));
 

components/scripts/lib/build-scan-offline.sh

@@ -49,7 +49,7 @@ read_build_scan_dumps() {
   )
 
   echo "Extracting Build Scan data for all builds"
-  if ! build_scan_data="$(invoke_java "$READ_BUILD_SCAN_DATA_JAR" "${args[@]}")"; then
+  if ! build_scan_data="$(JAVA_HOME="${CLIENT_JAVA_HOME:-$JAVA_HOME}" invoke_java "$READ_BUILD_SCAN_DATA_JAR" "${args[@]}")"; then
     exit "$UNEXPECTED_ERROR"
   fi
   echo "Finished extracting Build Scan data for all builds"

components/scripts/lib/build-scan-online.sh

@@ -101,5 +101,5 @@ fetch_build_scan_data() {
     args+=( "${run_num},${build_scan_urls[run_num]}" )
   done
 
-  invoke_java "${FETCH_BUILD_SCAN_DATA_JAR}" "${args[@]}"
+  JAVA_HOME="${CLIENT_JAVA_HOME:-$JAVA_HOME}" invoke_java "${FETCH_BUILD_SCAN_DATA_JAR}" "${args[@]}"
 }

release/changes.md

@@ -1,4 +1,5 @@
-- [NEW] Drops support for Gradle Enterprise versions older than 2023.1 when using `-e` command line option
+- [NEW] Drop support for Gradle Enterprise versions older than 2023.1 when using `-e` command line option
+- [NEW] Use `CLIENT_JAVA_HOME` environment variable to control the JVM used to analyze the Build Scan data
 - [FIX] Informs the Gradle Enterprise Gradle plugin that it is being applied externally when using `-e` command line option
 - [FIX] API requests do not allow time for build scans to become available
-- [FIX] Build caching configuration is not applied to child builds
+- [FIX] Build caching configuration is not applied to child builds