Add mill-jvm-index-version to build header keys (#6085)

Fixes #6072

Author: lihaoyi

example/cli/header/4-jvm-index-version/build.mill

@@ -0,0 +1,31 @@
+//| mill-jvm-index-version: 0.0.4-88-f9ba3d
+//| mill-jvm-version: temurin:11
+//
+// Mill uses the https://github.com/coursier/jvm-index[Coursier JVM Index] to resolve JVM
+// versions to their download location, as well as partially-qualified versions such as
+// `temurin:11` to the specific point version such as `temurin:11.0.28`. The version of
+// the JVM index is set by the version of Mill you are using, but you can override it
+// to use a newer JVM index (e.g. if you want to use a newly-released JVM not yet included
+// in Mill's jvm index version) or an older JVM index.
+//
+// The list of JVM index versions can be seen here:
+//
+// - https://repo1.maven.org/maven2/io/get-coursier/jvm/indices/[JVM Indices on Maven Central]
+//
+package build
+
+import mill._
+
+def printJavaVersion() = Task.Command {
+  println("Java version: " + System.getProperty("java.version"))
+}
+
+// This example uses an older `mill-jvm-index-version` to ensure the resolved version
+// of `temurin:11` gets appropriately downgraded from `11.0.28` (the most recent `11.x` version)
+// to `11.0.26` (the version of `11.x` available when the JVM index `0.0.4-88-f9ba3d` was released)
+/** Usage
+
+> ./mill printJavaVersion
+Java version: 11.0.26
+
+*/

runner/launcher/src/mill/launcher/CoursierClient.scala

@@ -47,19 +47,19 @@ object CoursierClient {
     artifactsResultOrError.artifacts.map(_._2.toString).toArray
   }
 
-  def resolveJavaHome(id: String): java.io.File = {
+  def resolveJavaHome(id: String, jvmIndexVersion: String = null): java.io.File = {
     val coursierCache0 = FileCache[Task]()
       .withLogger(coursier.cache.loggers.RefreshLogger.create())
+
+    val indexVersion =
+      if (jvmIndexVersion != null) jvmIndexVersion else mill.client.Versions.coursierJvmIndexVersion
     val jvmCache = JvmCache()
       .withArchiveCache(ArchiveCache().withCache(coursierCache0))
       .withIndex(
         JvmIndex.load(
           cache = coursierCache0,
           repositories = Resolve.defaultRepositories,
-          indexChannel = JvmChannel.module(
-            JvmChannel.centralModule(),
-            version = mill.client.Versions.coursierJvmIndexVersion
-          )
+          indexChannel = JvmChannel.module(JvmChannel.centralModule(), version = indexVersion)
         )
       )
 

runner/launcher/src/mill/launcher/MillProcessLauncher.java

@@ -166,6 +166,12 @@ static String millJvmVersion(OutFolderMode outMode) throws Exception {
     else return res.get(0);
   }
 
+  static String millJvmIndexVersion(OutFolderMode outMode) throws Exception {
+    List<String> res = loadMillConfig(outMode, "mill-jvm-index-version");
+    if (res.isEmpty()) return null;
+    else return res.get(0);
+  }
+
   static String millServerTimeout() {
     return System.getenv(EnvVars.MILL_SERVER_TIMEOUT_MILLIS);
   }
@@ -176,6 +182,7 @@ static boolean isWin() {
 
   static String javaHome(OutFolderMode outMode) throws Exception {
     var jvmId = millJvmVersion(outMode);
+    var jvmIndexVersion = millJvmIndexVersion(outMode);
 
     String javaHome = null;
     if (jvmId == null) {
@@ -184,11 +191,16 @@ static String javaHome(OutFolderMode outMode) throws Exception {
 
     if (jvmId != null) {
       final String jvmIdFinal = jvmId;
+      final String jvmIndexVersionFinal = jvmIndexVersion;
+      // Include JVM index version in the cache key to invalidate cache when index version changes
+      String cacheKey = jvmIndexVersion != null ? jvmId + ":" + jvmIndexVersion : jvmId;
       javaHome = cachedComputedValue0(
           outMode,
           "java-home",
-          jvmId,
-          () -> new String[] {CoursierClient.resolveJavaHome(jvmIdFinal).getAbsolutePath()},
+          cacheKey,
+          () -> new String[] {
+            CoursierClient.resolveJavaHome(jvmIdFinal, jvmIndexVersionFinal).getAbsolutePath()
+          },
           // Make sure we check to see if the saved java home exists before using
           // it, since it may have been since uninstalled, or the `out/` folder
           // may have been transferred to a different machine

website/docs/modules/ROOT/pages/cli/build-header.adoc

@@ -129,6 +129,10 @@ crashes and errors.
 For configuring different JVM versions for individual modules within your build, see
 xref:fundamentals/configuring-jvm-versions.adoc[Configuring JVM Versions].
 
+== mill-jvm-index-version
+
+include::partial$example/cli/header/4-jvm-index-version.adoc[]
+
 == mill-jvm-opts
 
 Mill supports `mill-jvm-opts` to set JVM-level flags