Improve example docs for assembly (#4336)

* Add example of copying `out.jar` to `out.bat` on windows
* Add example of configuring `JAVA_OPTS` and mention `JAVA_HOME`

.config/mill-version

@@ -1 +1 @@
-0.12.5-130-8f256f-DIRTY3537ab30-native
+0.12.5-130-8f256f-DIRTY3537ab30-native

example/javalib/basic/1-simple/build.mill

@@ -99,4 +99,9 @@ Test run foo.FooTest finished: 0 failed, 0 ignored, 2 total, ...
 > ./out/foo/assembly.dest/out.jar --text hello # mac/linux
 <h1>hello</h1>
 
+> cp ./out/foo/assembly.dest/out.jar out.bat # windows
+
+> ./out.bat --text hello # windows
+<h1>hello</h1>
+
 */

example/javalib/publishing/1-assembly-config/foo/src/foo/Foo.java

@@ -8,5 +8,6 @@ public static void main(String[] args) throws IOException {
     InputStream inputStream = Foo.class.getClassLoader().getResourceAsStream("application.conf");
     String conf = new String(inputStream.readAllBytes());
     System.out.println("Loaded application.conf from resources: " + conf);
+    System.out.println("Loaded test.property: " + System.getProperty("test.property"));
   }
 }

example/kotlinlib/basic/1-simple/build.mill

@@ -113,4 +113,8 @@ Test run finished: 0 failed, 0 ignored, 2 total, ...
 > ./out/foo/assembly.dest/out.jar --text hello # mac/linux
 <h1>hello</h1>
 
+> cp ./out/foo/assembly.dest/out.jar out.bat # windows
+
+> ./out.bat --text hello # windows
+<h1>hello</h1>
 */

example/kotlinlib/publishing/1-assembly-config/foo/src/foo/Foo.kt

@@ -8,4 +8,5 @@ fun main(args: Array<String>) {
             val conf = it.readAllBytes().toString(Charsets.UTF_8)
             println("Loaded application.conf from resources: $conf")
         }
+    println("Loaded test.property: " + System.getProperty("test.property"))
 }

example/scalalib/basic/1-simple/build.mill

@@ -119,6 +119,12 @@ error: Missing argument: --text <str>
 > ./out/foo/assembly.dest/out.jar --text hello # mac/linux
 <h1>hello</h1>
 
+> # Note that on windows you need to rename `out.jar` to `out.bat` to run it
+> cp ./out/foo/assembly.dest/out.jar out.bat # windows
+
+> ./out.bat --text hello # windows
+<h1>hello</h1>
+
 */
 
 //// SNIPPET:END

example/scalalib/publishing/1-assembly-config/build.mill

@@ -47,3 +47,14 @@ Loaded application.conf from resources:...
 ...Bar Application Conf
 
 */
+
+// Note that when running the assembly directly via `./out.jar`, you can configure
+// JVM flags via the `JAVA_OPTS` environment variable, and select the JVM
+// to use via `JAVA_HOME`.
+
+/** Usage
+
+> JAVA_OPTS=-Dtest.property=1337 ./out/foo/assembly.dest/out.jar
+Loaded test.property: 1337
+
+*/

example/scalalib/publishing/1-assembly-config/foo/src/Foo.scala

@@ -3,5 +3,6 @@ object Foo {
   def main(args: Array[String]): Unit = {
     val conf = os.read(os.resource / "application.conf")
     println("Loaded application.conf from resources: " + conf)
+    println("Loaded test.property: " + System.getProperty("test.property"))
   }
 }

testkit/src/mill/testkit/ExampleTester.scala

@@ -114,13 +114,19 @@ class ExampleTester(
          |------------------------------""".stripMargin
     )
 
+    val windowsPathEnv =
+      if (!Util.windowsPlatform) Map()
+      else Map(
+        "BASH_ENV" -> os.temp("export PATH=\"/c/Program Files/Git/usr/bin:$PATH\"").toString()
+      )
+
     val res = os.call(
       (bashExecutable, "-c", commandStr),
       stdout = os.Pipe,
-      stderr = os.Pipe,
+      stderr = os.Inherit,
       cwd = workspacePath,
       mergeErrIntoOut = true,
-      env = IntegrationTester.millTestSuiteEnv,
+      env = IntegrationTester.millTestSuiteEnv ++ windowsPathEnv,
       check = false
     )