Make ./mill without any arguments point you towards --help, flesh out --help into a cheat sheet

[lihaoyi]

Fixes #3547

I added the cheat sheet for task syntax and compacted the flag documentation so it all fits on one page in the default macbook pro 15" terminal half screen at the default font size, with some room to spare vertically and horizontally: ~55 characters tall and ~100 characters wide. Could always squeeze it more or less, and the choice of target size is arbitrary, but this should be both concise and information-dense while still giving newbies a lot of useful tips and pointers. Notably, having too much detail in any part of this blurb is a net negative: it needs to be maximally concise while still containing the most useful pieces of information. More detailed explanations and exposition can go to the doc-site, which I linked at the bottom of the cheat sheet

I also split the usageText into shortUsageText which is printed on ./mill, and long usage text which is printed on ./mill --help, with the short usage text pointing you at ./mill --help for more details:

lihaoyi mill$ ./mill
Please specify a task to evaluate

Usage: mill [options] task [task-options] [+ task ...]
Run `./mill --help` for more details

lihaoyi mill$ ./mill --help
Mill Build Tool, version 0.12.0-RC2-13-921d96-DIRTY16b6c61b
Usage: mill [options] [[task [task-options]] [+ [task ...]]]

task cheat sheet:
  mill resolve _                 # see all top-level tasks and modules
  mill resolve __.compile        # see all `compile` tasks in any module (recursively)

  mill foo.bar.compile           # compile the module `foo.bar`

  mill foo.run --arg 1           # run the main method of the module `foo` and pass in `--arg 1`
  mill -i foo.console            # run the Scala console for the module `foo` (if it is a ScalaModule)

  mill foo.__.test               # run tests in module within `foo` (recursively)
  mill foo.test arg1 arg2        # run tests in the `foo` module passing in test arguments `arg1 arg2`
  mill foo.test + bar.test       # run tests in the `foo` module and `bar` module
  mill '{foo,bar,qux}.test'      # run tests in the `foo` module, `bar` module, and `qux` module

  mill foo.assembly              # generate an executable assembly of the module `foo`
  mill show foo.assembly         # print the output path of the assembly of module `foo`
  mill inspect foo.assembly      # show docs and metadata for the `assembly` task on module `foo`

  mill clean foo.assembly        # delete the output of `foo.assembly` to force re-evaluation
  mill clean                     # delete the output of the entire build to force force re-evaluation

  mill path foo.run foo.sources  # print the task chain showing how `foo.run` depends on `foo.sources`
  mill visualize __.compile      # show how the `compile` tasks in each module depend on one another

options:
  -D --define <k=v>    Define (or overwrite) a system property.
  --allow-positional   Allows command args to be passed positionally without `--arg` by default
  -b --bell            Ring the bell once if the run completes successfully, twice if it fails.
  --bsp                Enable BSP server mode.
  --color <bool>       Toggle colored output; by default enabled only if the console is interactive
  -d --debug           Show debug output on STDOUT
  --disable-callgraph  Disables fine-grained invalidation of tasks based on analyzing code changes.
                       If passed, you need to manually run `clean` yourself after build changes.
  --help               Print this help message and exit.
  -i --interactive     Run Mill in interactive mode, suitable for opening REPLs and taking user
                       input. This implies --no-server. Must be the first argument.
  --import <str>       Additional ivy dependencies to load into mill, e.g. plugins.
  -j --jobs <int>      The number of parallel threads. It can be an integer e.g. `5` meaning 5
                       threads, an expression e.g. `0.5C` meaning half as many threads as available
                       cores, or `C-2` meaning 2 threads less than the number of cores. `1` disables
                       parallelism and `0` (the default) uses 1 thread per core.
  -k --keep-going      Continue build, even after build failures.
  --meta-level <int>   Select a meta-level to run the given targets. Level 0 is the main project in
                       `build.mill`, level 1 the first meta-build in `mill-build/build.mill`, etc.
  --no-server          Run without a background server. Must be the first argument.
  -s --silent          Make ivy logs during script import resolution go silent instead of printing
  --ticker <bool>      Enable ticker log (e.g. short-lived prints of stages and progress bars).
  -v --version         Show mill version information and exit.
  -w --watch           Watch and re-run the given tasks when when their inputs change.
  target <str>...      The name or a pattern of the target(s) you want to build.

Please see the documentation at https://mill-build.org for more details

In the process I shortened the names and docs of a lot of the flags that were IMO overly verbose. Especially for more advanced features like --meta-level we can get away with a more terse explanation here since the docs go into much more detail

As we do not guarantee bincompat for the mill.runner package, so we do not need to add shims and forwarders as we evolve the case class MillCliConfig

Notably this default blurb does not include any information about the current build, and is very generic. I don't know what the best way of inferring which modules and tasks are "important" and which are not, and so for now I just punted on the issue and just try to show syntax and tasks that should be useful for any Mill build. For now still somewhat JVM specific with compile and assembly and test; if in the future we start having more non-JVM stuff built using Mill we can make further changes then

[lefou]

Making Mill CLI no longer accept the same old arguments means, failing in various places where Mill is used in scripts. Also many users don't have a strong idea which version of Mill they currently using, since it's not controlled by their system but by some random .mill-version file.

Even if we don't need to produce binary compatible packages, we should have a grace period for CLI options. Any CLI option no longer accepted will be interpreted as target and most likely break some workflow. Instead, we should deprecate those options, print a warning and either ignore them if no longer supported, or internally translate to their new meaning like e.g. for --disable-ticker. Even if no users will thank us (which is normal), if we don't do that, many will have a harder time.

The mill-integrationtest plugin used by some other plugins will definitely break when this PR gets merged unchanged.

[lefou]

I'd rather get rid of it entirely. It's a relict from Ammonite and we only have it still, since it's part exposed in our API (T.home). The only thing we put there is the Java rt.jar which we generate if missing and share between projects. In essence, we don't look for config here, really.

[lolgab]

Maybe installing global JVMs could require it?
We have this issue: #3480

[lihaoyi]

I hid/deprecated it for now

[lefou]

We should add the syntax guide from your screenshot to mill --help in general.

Otherwise, this is a nice topic for bikeshedding, but I would prefer shorter two line error message saying there is no target and indicating that mill --help will reveal more information.

[lefou]

We should add the syntax guide from your screenshot to mill --help in general.

Otherwise, this is a nice topic for bikeshedding, but I would prefer shorter two line error message saying there is no target and indicating that mill --help will reveal more information.

A bit more motivation. The long error message might help beginners, but the long message might always get in the way now and then to the power user, when she fingered or pressed enter too fast. Needing to scroll back to focus on what the last action/output/command was.

[lihaoyi]

I put back the enableTicker/disableTicker flags but marked them as hidden/deprecated. They still work, but they don't show up in the UI. I guess we can leave them there in perpetuity.

I also split the usageText into shortUsageText which is printed on ./mill, and long usage text which is printed on ./mill --help, with the short usage text pointing you at ./mill --help for more details:

lihaoyi mill$ ./mill
Mill Build Tool, version 0.12.0-RC2-13-921d96-DIRTY16b6c61b
usage: mill [options] [[target [target-options]] [+ [target ...]]]
Run `./mill --help` for more details

lihaoyi mill$ ./mill --help
Mill Build Tool, version 0.12.0-RC2-13-921d96-DIRTY16b6c61b
usage: mill [options] [[target [target-options]] [+ [target ...]]]

target cheat sheet:
  ./mill resolve _                 # see all top-level tasks and modules
  ./mill resolve __.compile        # see all `compile` tasks in any module (recursively)

  ./mill foo.bar.compile           # compile the module `foo.bar`

  ./mill foo.run --arg 1           # run the main method of the module `foo` and pass in `--arg 1`
  ./mill -i foo.console            # run the Scala console for the module `foo` (if it is a ScalaModule)

  ./mill foo.__.test               # run tests in module within `foo` (recursively)
  ./mill foo.test arg1 arg2        # run tests in the `foo` module passing in test arguments `arg1 arg2`
  ./mill foo.test + bar.test       # run tests in the `foo` module and `bar` module
  ./mill '{foo,bar,qux}.test'      # run tests in the `foo` module, `bar` module, and `qux` module

  ./mill foo.assembly              # generate an executable assembly of the module `foo`
  ./mill show foo.assembly         # print the output path of the assembly of module `foo`
  ./mill inspect foo.assembly      # show docs and metadata for the `assembly` task on module `foo`

  ./mill clean foo.assembly        # delete the output of `foo.assembly` to force re-evaluation
  ./mill clean                     # delete the output of the entire build to force force re-evaluation

  ./mill path foo.run foo.sources  # print the task chain showing how `foo.run` depends on `foo.sources`
  ./mill visualize __.compile      # show how the `compile` tasks in each module depend on one another

options:
  -D --define <k=v>    Define (or overwrite) a system property.
  --allow-positional   Allows command args to be passed positionally without `--arg` by default
  -b --bell            Ring the bell once if the run completes successfully, twice if it fails.
  --bsp                Enable BSP server mode.
  --color <bool>       Toggle colored output; by default enabled only if the console is interactive
  -d --debug           Show debug output on STDOUT
  --disable-callgraph  Disables fine-grained invalidation of tasks based on analyzing code changes.
                       If passed, you need to manually run `clean` yourself after build changes.
  --help               Print this help message and exit.
  -i --interactive     Run Mill in interactive mode, suitable for opening REPLs and taking user
                       input. This implies --no-server. Must be the first argument.
  --import <str>       Additional ivy dependencies to load into mill, e.g. plugins.
  -j --jobs <int>      The number of parallel threads. It can be an integer e.g. `5` meaning 5
                       threads, an expression e.g. `0.5C` meaning half as many threads as available
                       cores, or `C-2` meaning 2 threads less than the number of cores. `1` disables
                       parallelism and `0` (the default) uses 1 thread per core.
  -k --keep-going      Continue build, even after build failures.
  --meta-level <int>   Select a meta-level to run the given targets. Level 0 is the main project in
                       `build.mill`, level 1 the first meta-build in `mill-build/build.mill`, etc.
  --no-server          Run without a background server. Must be the first argument.
  -s --silent          Make ivy logs during script import resolution go silent instead of printing
  --ticker <bool>      Enable ticker log (e.g. short-lived prints of stages and progress bars).
  -v --version         Show mill version information and exit.
  -w --watch           Watch and re-run the given tasks when when their inputs change.
  target <str>...      The name or a pattern of the target(s) you want to build.

Please see the documentation at https://mill-build.org for more details

[lefou]

usage: mill [options] [[target [target-options]] [+ [target ...]]]

I think this synopsis isn't correct. The first target isn't optional, except when running with --version or --help.

[lihaoyi]

usage: mill [options] [[target [target-options]] [+ [target ...]]]

I think this synopsis isn't correct. The first target isn't optional, except when running with --version or --help.

Updated it to

usage: mill [options] target [target-options] [+ target ...]

So the first target is necessary, the target-options is optional ,and the + target ... is also optional

[lefou]

lihaoyi mill$ ./mill

> ./mill 
Mill Build Tool, version 0.12.0-RC2-13-921d96-DIRTY16b6c61b
usage: mill [options] [target [target-options] [+ [target ...]]]
Run `./mill --help` for more details

We now just say, look at the help, without telling what the problem is, although we know the problem, a missing target.

Should be:

-Mill Build Tool, version 0.12.0-RC2-13-921d96-DIRTY16b6c61b
+ A target is missing.
+
-usage: mill [options] [target [target-options] [+ [target ...]]]
+Usage: mill [options] [target [target-options] [+ [target ...]]]
-Run `./mill --help` for more details
+Run `mill --help` for more details

[lihaoyi]

I went with Please specify a task to evaluate, and in general replaced most of the usage of target with task. The term target doesn't really match the type hierarchy (e.g. Commands are not Targets), and #3356 is going to standardize on the type/term Task later on, so starting to use it here too

[lihaoyi]

Also removed all the leading ./ since those don't really convey any meaning and add a lot of visual noise to the cheatsheet