This PR is still Work in progress, mostly because not all examples are migrated and the API may change. Nevertheless the concept is open for discussion. Please engage!

Summary

BINARY BREAKING CHANGES!

Related to:

• Makeout/ 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 newmill.api.opt API containing the classesOpts,Opt andOptGroup.

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 namedOpts, notArgs, since we already have amill.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 useOpts instead ofSeq. In case, some non-Seq-like structures are needed, likeMap, the single-elementOpt 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]]

More types?

Feel free to discuss, if more data structure are needed. E.g. theMap[String, Opt] could also be represented asOptsMap, so more value types could be accepted on the rhs, eliminating one error source and resulting in more concise code.

JSON serialization

The JSON sturcture is more complex that the previousSeq[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 complexOpts 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 allSeq[String] can easily be read asOpts. This was done to make working withOpts as convenient asSeq[String] not only in Scala code but also inYAML configuration code.

This means,build.mill YAML frontmatter andbuild.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"}] }

Caveats

In this current POC, we need to addimport mill.api.opt.*. I'm glad for ideas, how to improve this and make it a single import.