Consolidate and document Mill environment variables (#3378)

Also got rid of `MILL_TEST_DEST_FOLDER` since
#3347 makes `os.pwd` sufficient.

There are also a few other `MILL_*` things that look like env vars but
are actually system properties, so I left them out of this PR

example/javamodule/5-resources/foo/test/src/FooTests.java

@@ -49,4 +49,4 @@ public void simple() throws IOException {
     );
     assertEquals("Other Hello World File", otherFileText);
   }
-}
+}

main/api/src/mill/api/WorkspaceRoot.scala

@@ -1,6 +1,7 @@
 package mill.api
 
-import os.Path
+import mill.main.client.EnvVars
 object WorkspaceRoot {
-  val workspaceRoot: Path = sys.env.get("MILL_WORKSPACE_ROOT").fold(os.pwd)(os.Path(_, os.pwd))
+  val workspaceRoot: os.Path =
+    sys.env.get(EnvVars.MILL_WORKSPACE_ROOT).fold(os.pwd)(os.Path(_, os.pwd))
 }

main/client/src/mill/main/client/EnvVars.java

@@ -0,0 +1,43 @@
+package mill.main.client;
+
+/**
+ * Central place containing all the environment variables that Mill uses
+ */
+public class EnvVars {
+    // USER FACING ENVIRONMENT VARIABLES
+
+    /**
+     * Available in test modules for users to find the test resource folder on disk
+     * in a convenient fashion. If multiple resource folders are provided on the classpath,
+     * they are provided as a comma-separated list
+     */
+    public static final String MILL_TEST_RESOURCE_FOLDER = "MILL_TEST_RESOURCE_FOLDER";
+
+    /**
+     * How long the Mill background server should run before timing out from inactivity
+     */
+    public static final String MILL_SERVER_TIMEOUT_MILLIS = "MILL_SERVER_TIMEOUT_MILLIS";
+
+
+    public static final String MILL_JVM_OPTS_PATH = "MILL_JVM_OPTS_PATH";
+
+    // INTERNAL ENVIRONMENT VARIABLES
+    /**
+     * Used to pass the Mill workspace root from the client to the server, so
+     * the server code can access it despite it not being os.pwd
+     */
+    public static final String MILL_WORKSPACE_ROOT = "MILL_WORKSPACE_ROOT";
+
+    /**
+     * Used to indicate to Mill that it is running as part of the Mill test suite,
+     * e.g. to turn on additional testing/debug/log-related code
+     */
+    public static final String MILL_TEST_SUITE = "MILL_TEST_SUITE";
+
+    /**
+     * Used to indicate to the Mill test suite which libraries should be resolved from
+     * the local disk and not from Maven Central
+     */
+    public static final String MILL_BUILD_LIBRARIES = "MILL_BUILD_LIBRARIES";
+
+}

main/eval/src/mill/eval/EvaluatorCore.scala

@@ -6,6 +6,7 @@ import mill.api._
 import mill.define._
 import mill.eval.Evaluator.TaskResult
 import mill.main.client.OutFiles._
+import mill.main.client.EnvVars
 import mill.util._
 
 import java.util.concurrent.atomic.{AtomicBoolean, AtomicInteger}
@@ -170,7 +171,7 @@ private[mill] trait EvaluatorCore extends GroupEvaluator {
       tasks,
       // We want to skip the non-deterministic thread prefix in our test suite
       // since all it would do is clutter the testing logic trying to match on it
-      if (sys.env.contains("MILL_TEST_SUITE")) _ => ""
+      if (sys.env.contains(EnvVars.MILL_TEST_SUITE)) _ => ""
       else contextLoggerMsg0
     )(ec)
     evaluateTerminals(leafCommands, _ => "")(ExecutionContexts.RunNow)

main/server/test/src/mill/main/server/ClientServerTests.scala

@@ -122,7 +122,7 @@ object ClientServerTests extends TestSuite {
 
   def tests = Tests {
     val tester = new Tester
-    "hello" - {
+    "hello" - retry(3) {
 
       val res1 = tester(args = Array("world"))
 

main/test/src/mill/util/TestUtil.scala

@@ -12,10 +12,7 @@ import scala.collection.mutable
 
 object TestUtil extends MillTestKit {
 
-  override val targetDir = sys.env.get("MILL_TEST_DEST_FOLDER") match {
-    case Some(v) => os.Path(v)
-    case None => os.pwd / "target"
-  }
+  override val targetDir = os.pwd / "target"
 
   def getOutPath()(implicit fullName: sourcecode.FullName, tp: TestPath): os.Path = {
     getOutPath(tp.value)

main/testkit/src/mill/testkit/MillTestkit.scala

@@ -15,8 +15,7 @@ import os.Path
 
 trait MillTestKit {
 
-  def defaultTargetDir: os.Path =
-    sys.env.get("MILL_TESTKIT_BASEDIR").map(os.pwd / os.RelPath(_)).getOrElse(os.temp.dir())
+  def defaultTargetDir: os.Path = os.temp.dir(os.pwd)
 
   def targetDir: os.Path = defaultTargetDir
 

runner/client/src/mill/runner/client/MillProcessLauncher.java

@@ -9,6 +9,7 @@
 import mill.main.client.Util;
 import mill.main.client.ServerFiles;
 import mill.main.client.ServerCouldNotBeStarted;
+import mill.main.client.EnvVars;
 
 public class MillProcessLauncher {
 
@@ -45,15 +46,15 @@ static void launchMillServer(String serverDir, boolean setJnaNoSys) throws Excep
 
     static Process configureRunMillProcess(ProcessBuilder builder,
                                            String serverDir) throws Exception {
-        builder.environment().put("MILL_WORKSPACE_ROOT", new File("").getCanonicalPath());
+        builder.environment().put(EnvVars.MILL_WORKSPACE_ROOT, new File("").getCanonicalPath());
         File sandbox = new java.io.File(serverDir + "/" + ServerFiles.sandbox);
         sandbox.mkdirs();
         builder.directory(sandbox);
         return builder.start();
     }
 
     static File millJvmOptsFile() {
-        String millJvmOptsPath = System.getenv("MILL_JVM_OPTS_PATH");
+        String millJvmOptsPath = System.getenv(EnvVars.MILL_JVM_OPTS_PATH);
         if (millJvmOptsPath == null || millJvmOptsPath.trim().equals("")) {
             millJvmOptsPath = ".mill-jvm-opts";
         }
@@ -66,7 +67,7 @@ static boolean millJvmOptsAlreadyApplied() {
     }
 
     static String millServerTimeout() {
-        return System.getenv("MILL_SERVER_TIMEOUT_MILLIS");
+        return System.getenv(EnvVars.MILL_SERVER_TIMEOUT_MILLIS);
     }
 
     static boolean isWin() {

scalalib/src/mill/scalalib/Lib.scala

@@ -5,6 +5,7 @@ import coursier.util.Task
 import coursier.{Dependency, Repository, Resolution}
 import mill.api.{Ctx, Loose, PathRef, Result}
 import mill.main.BuildInfo
+import mill.main.client.EnvVars
 import mill.util.Util
 import mill.scalalib.api.ZincWorkerUtil
 
@@ -147,7 +148,7 @@ object Lib {
       ctx: Option[mill.api.Ctx.Log],
       useSources: Boolean
   ): Seq[os.Path] = {
-    Util.millProperty("MILL_BUILD_LIBRARIES") match {
+    Util.millProperty(EnvVars.MILL_BUILD_LIBRARIES) match {
       case Some(found) => found.split(',').map(os.Path(_)).distinct.toList
       case None =>
         millAssemblyEmbeddedDeps

scalalib/src/mill/scalalib/RunModule.scala

@@ -3,6 +3,7 @@ package mill.scalalib
 import mill.api.JsonFormatters.pathReadWrite
 import mill.api.{Ctx, PathRef, Result}
 import mill.define.{Command, Task}
+import mill.main.client.EnvVars
 import mill.util.Jvm
 import mill.{Agg, Args, T}
 import os.{Path, ProcessOutput}
@@ -161,7 +162,7 @@ trait RunModule extends WithZincWorker {
 
       // Make sure to sleep a bit in the Mill test suite to allow the servers we
       // start time to initialize before we proceed with the following commands
-      if (T.env.contains("MILL_TEST_SUITE")) {
+      if (T.env.contains(EnvVars.MILL_TEST_SUITE)) {
         println("runBackgroundTask SLEEPING 10000")
         Thread.sleep(5000)
       }

scalalib/src/mill/scalalib/TestModule.scala

@@ -1,6 +1,7 @@
 package mill.scalalib
 
 import mill.api.{Ctx, PathRef, Result}
+import mill.main.client.EnvVars
 import mill.define.{Command, Task, TaskModule}
 import mill.scalalib.bsp.{BspBuildTarget, BspModule}
 import mill.testrunner.{Framework, TestArgs, TestResult, TestRunner, TestRunnerUtils}
@@ -191,10 +192,9 @@ trait TestModule
             _.path
           ),
         jvmArgs = jvmArgs,
-        envArgs = Map(
-          "MILL_TEST_RESOURCE_FOLDER" -> resources().map(_.path).mkString(";"),
-          "MILL_TEST_DEST_FOLDER" -> T.dest.toString()
-        ) ++ forkEnv(),
+        envArgs =
+          Map(EnvVars.MILL_TEST_RESOURCE_FOLDER -> resources().map(_.path).mkString(";")) ++
+            forkEnv(),
         mainArgs = mainArgs,
         workingDir = if (testSandboxWorkingDir()) T.dest / "sandbox" else forkWorkingDir(),
         useCpPassingJar = useArgsFile