Allow running standalone single-file scripts using Mill (#5820)

First pass at #5714

Initial pass, this works:

```
$ ./mill -f Foo.java run --text hello

[6972/6972] dist.run
watching processId file (expected content = 63396): /Users/lihaoyi/Github/mill/test/out/mill-no-daemon/pid-63396/processId
============================== run --text hello ==============================
[55/55] run
[55] SLF4J: No SLF4J providers were found.
[55] SLF4J: Defaulting to no-operation (NOP) logger implementation
[55] SLF4J: See https://www.slf4j.org/codes.html#noProviders for further details.
[55] <h1>hello</h1>
[55/55] ============================== run --text hello ==============================
[6972/6972] ============================== dist.run test -i -f Foo.java run --text hello ============================== 1s
```

The basic approach is 

- Allow `-f`/`--file` to be passed to specify a script file to use
rather than `build.mill`
- If `-f` is passed, use an alternate shortened `MillBuildBootstrap`
process that has a single build stage with a hard-coded `RootModule`
based on the extension of the script: `mill.meta.ScriptModule.Java`,
`.Scala`, or `.Kotlin`

In the common case where someone wants to just run a script, they can
run:

```
./mill Foo.java --text hello
```

As a shorthand for the full `./mill -f Foo.java run --text hello`. We
special-case the first token ending with `.java`, `.scala`, or `.kt` to
support this. I expect this would be what people want to do with their
scripts the vast majority of the time, so it deserves its own
extra-concise syntax even if it has some theoretical overlap with
user-defined tasks ending with those names

Other notes: 

- For single-file projects, we assign them a subfolder in the out folder
where all the build takes place e.g. `foo/bar/Baz.kt` gets assigned
`out/foo/bar/Baz.kt/` as its out folder. Normal tasks and modules won't
normally have `.`s in their name, so this ensures that the single-file
projects won't collide with normal module and task output files

- Some of the task outputs from `mill.javalib.publish` have been given
short-hands `upickle.Reader`s for writing them in the YAML build header.
I expect we will need to add more such shorthands in future

- Started with some basic doc sections on the per-language `intro.adoc`
and `module-config.adoc` pages touching on usage of these single-file
projects, but I expect we'll need more documentation

- For this PR, the single-file projects are entirely standalone and not
connected to any enclosing Mill build, but that may be something we can
integrate in future to allow single-file projects to define `moduleDeps`
on the enclosing `build.mill`'s modules

Tested with a example tests

Author: lihaoyi

.editorconfig

@@ -18,6 +18,12 @@ indent_size = 2
 ktlint_code_style = intellij_idea
 ktlint_standard_no-wildcard-imports = disabled
 
+[example/kotlinlib/basic/5-single-file/**/*]
+ktlint = disabled
+
+[example/kotlinlib/module/1-single-file/**/*]
+ktlint = disabled
+
 [example/kotlinlib/linting/**/*]
 ktlint = disabled
 

build.mill

@@ -1,4 +1,4 @@
-//| mill-version: 1.0.4-26-a6e4c1
+//| mill-version: 1.0.4-38-cbb9e8
 //| mill-jvm-opts: ["-XX:NonProfiledCodeHeapSize=250m", "-XX:ReservedCodeCacheSize=500m"]
 //| mill-opts: ["--jobs=0.5C"]
 

core/constants/src/mill/constants/Util.java

@@ -5,6 +5,8 @@
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 import java.util.ArrayList;
@@ -84,15 +86,20 @@ private static String throwBuildHeaderError(
         + ": " + line + "\n" + msg);
   }
 
-  public static String readBuildHeader(java.nio.file.Path buildFile, String errorFileName) {
+  public static String readBuildHeader(Path buildFile, String errorFileName) {
+    return readBuildHeader(buildFile, errorFileName, false);
+  }
+
+  public static String readBuildHeader(
+      Path buildFile, String errorFileName, boolean allowNonBuild) {
     try {
-      java.util.List<String> lines = java.nio.file.Files.readAllLines(buildFile);
+      java.util.List<String> lines = Files.readAllLines(buildFile);
       boolean readingBuildHeader = true;
       java.util.List<String> output = new ArrayList<>();
       for (int i = 0; i < lines.size(); i++) {
         String line = lines.get(i);
         if (!line.startsWith("//|")) readingBuildHeader = false;
-        else if (!buildFile.getFileName().toString().startsWith("build.")) {
+        else if (!allowNonBuild && !buildFile.getFileName().toString().startsWith("build.")) {
           throwBuildHeaderError(
               errorFileName,
               i,

core/internal/cli/package.mill

@@ -9,8 +9,5 @@ import millbuild.*
 object `package` extends MillPublishScalaModule {
   def moduleDeps = Seq(build.libs.util)
 
-  def mvnDeps = Seq(
-    Deps.millModuledefs,
-    Deps.mainargs
-  )
+  def mvnDeps = Seq(Deps.mainargs)
 }

core/internal/cli/src/mill/internal/MillCliConfig.scala

@@ -128,6 +128,11 @@ case class MillCliConfig(
       doc = """Runs Mill in tab-completion mode"""
     )
     tabComplete: Flag = Flag(),
+    @arg(
+      short = 'f',
+      doc = """Select the build.mill file or Java/Scala/Kotlin script file to run"""
+    )
+    file: Option[os.Path] = None,
 
     // ==================== DEPRECATED CLI FLAGS ====================
     @arg(hidden = true, short = 'h', doc = "Unsupported")

example/javalib/basic/5-single-file/Foo.java

@@ -0,0 +1,35 @@
+//| mvnDeps:
+//| - "net.sourceforge.argparse4j:argparse4j:0.9.0"
+//| - "org.thymeleaf:thymeleaf:3.1.1.RELEASE"
+import net.sourceforge.argparse4j.ArgumentParsers;
+import net.sourceforge.argparse4j.inf.ArgumentParser;
+import net.sourceforge.argparse4j.inf.Namespace;
+import org.thymeleaf.TemplateEngine;
+import org.thymeleaf.context.Context;
+
+public class Foo {
+  public static String generateHtml(String text) {
+    Context context = new Context();
+    context.setVariable("text", text);
+    return new TemplateEngine().process("<h1 th:text=\"${text}\"></h1>", context);
+  }
+
+  public static void main(String[] args) {
+    ArgumentParser parser = ArgumentParsers.newFor("template")
+        .build()
+        .defaultHelp(true)
+        .description("Inserts text into a HTML template");
+
+    parser.addArgument("-t", "--text").required(true).help("text to insert");
+
+    Namespace ns = null;
+    try {
+      ns = parser.parseArgs(args);
+    } catch (Exception e) {
+      System.out.println(e.getMessage());
+      System.exit(1);
+    }
+
+    System.out.println(generateHtml(ns.getString("text")));
+  }
+}

example/javalib/basic/5-single-file/build.mill

@@ -0,0 +1,30 @@
+//// SNIPPET:FILE
+/** See Also: Foo.java */
+/** Usage
+> ./mill Foo.java --text hello
+compiling 1 Java source to...
+<h1>hello</h1>
+*/
+
+/** Usage
+> ./mill -f Foo.java run --text hello
+<h1>hello</h1>
+*/
+
+//// SNIPPET:END
+//// SNIPPET:MORE
+
+/** Usage
+> ./mill -f Foo.java show assembly # show the output of the assembly task
+".../out/Foo.java/assembly.dest/out.jar"
+
+> java -jar ./out/Foo.java/assembly.dest/out.jar --text hello
+<h1>hello</h1>
+
+> ./out/Foo.java/assembly.dest/out.jar --text hello # mac/linux
+<h1>hello</h1>
+
+
+*/
+
+//// SNIPPET:END

example/javalib/module/1-single-file/Bar.java

@@ -0,0 +1,17 @@
+//| jvmId: "graalvm-community:24"
+//| nativeImageOptions: ["--no-fallback"]
+//| publishVersion: "0.0.1"
+//| artifactName: "example"
+//| pomSettings:
+//|   description: "Example"
+//|   organization: "com.lihaoyi"
+//|   url: "https://github.com/com.lihaoyi/example"
+//|   licenses: ["MIT"]
+//|   versionControl: "https://github.com/com.lihaoyi/example"
+//|   developers: [{"name": "Li Haoyi", "email": "[email protected]"}]
+
+public class Bar {
+  public static void main(String[] args) {
+    System.out.println("Hello Graal Native: " + System.getProperty("java.version"));
+  }
+}

example/javalib/module/1-single-file/build.mill

@@ -0,0 +1,24 @@
+//// SNIPPET:LAST
+
+/** See Also: Bar.java */
+/** Usage
+
+> ./mill -f Bar.java nativeImage
+
+> out/Bar.java/nativeImage.dest/native-executable
+Hello Graal Native: 24...
+
+> ./mill -f Bar.java publishLocal
+Publishing Artifact(com.lihaoyi,example...,0.0.1) to ivy repo ...
+
+*/
+
+// Apart from publishing locally, you can also publish this single-file project to
+// Sonatype Maven Central via:
+//
+// [source,console]
+// ----
+// > ./mill -f Bar.java mill.javalib.SonatypeCentralPublishModule/
+// ----
+
+//// SNIPPET:END