[WIP] POC Opts (Args) concept

[lefou]

WIP

Summary

BINARY BREAKING CHANGES!

Related to:

• Make out/ folder contents (more) reproducible and filesystem layout agnostic #3660 - Tracker issue
• Dynamically map known root paths in cache files #6031 - Stores relocatable paths
• new `Args` class for relocateable configurations #6057 - Idea that drives this PR about how to store relocatable configuration options

This PR contains:

1. The new mill.api.opt API containing the classes Opts, Opt and OptGroup.

2. A refactoring of various modules that contain configuration data potentially containing paths - this is a API breaking change to just proof the concept

In contrast to the proposal (#6057) the class is named Opts, not Args, since we already have a mill.api.Args class used for other purposes.

While this PR can be applied as-is, it's real effect only emerges when also PR #6031 is merged, since otherwise, the paths stored as part of the configuration data will not be relocatable.

API changes in detail

All tasks containing configuration data that also may contain file or directory paths should use Opts instead of Seq. In case, some non-Seq-like structures are needed, like Map, the single-element Opt can be used for values.

Most prominent tasks are:

• javacOptions: T[Seq[String]] --> T[Opts]
• scalacOptions: T[Seq[String]] --> T[Opts]
• kotlincOptions: T[Seq[String]] --> T[Opts]
• forkArgs: T[Seq[String]] --> T[Opts]
• forkEnv: T[Map[String, String]] --> T[Map[String, Opt]]`

JSON serialization

The JSON sturcture is more complex that the previous Seq[String] equivalent, because it needs to support options, option groups and multi-parts options, which may itself consist of many strings and paths.

A rather complex Opts JSON serialization may look like this:

Opts(
  "-deprecated", 
  OptGroup("-classpath", Opt.mkPath(classpath, sep = ":"))
)

[
  "-deprecated",
  [
    "-classpath",
    [
      { "path": "/path/to/jar1.jar" },
      ":",
      { "path": "/path/to/jar2.jar" },
      ":",
      { "path": "/path/to/jar3.jar" }
    ]
  ]
]

Since the JSON serialization for paths re-use the respective upickle-serializers, the root path mapping of PR #6031 may also work here (Resulting is paths like $MILL_OUT/task/to/jar.dest/out.jar).

YAML convenience

In addition, the json reader supports reading of flat json arrays, which means, that all Seq[String] can easily be read as Opts. This was done to make working with Opts as convenient as Seq[String] not only in Scala code but also in YAML configuration code.

This means, build.mill YAML frontmatter and build.mill.yaml don't need any changes.

mill-build:
  scalacOptions: ["-verbose"]
  forkEnv: { "MY_CUSOTM_ENV": "my-env-value" }

Although the full encoding is also supported but seldomly required.

mill-build:
  forkArgs: [[["-javaagent:", {"path": "$WORKSPACE/agent.jar"}]]]
  forkEnv: { "MY_WORK_DIR": [{"path": "$HOME/workDir"}] }