Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make
./mill without any arguments point you towards --help, flesh…
… out `--help` into a cheat sheet (#3556) 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
- Loading branch information
