diff options
-rw-r--r-- | core/src/mill/util/Logger.scala | 4 | ||||
-rw-r--r-- | docs/cross.md | 38 | ||||
-rw-r--r-- | docs/extending.md | 22 | ||||
-rw-r--r-- | docs/index.md | 17 | ||||
-rw-r--r-- | docs/intro.md | 179 | ||||
-rw-r--r-- | docs/modules.md | 12 | ||||
-rw-r--r-- | docs/publishing.md | 0 | ||||
-rw-r--r-- | main/src/mill/main/ReplApplyHandler.scala | 4 | ||||
-rw-r--r-- | readme.md | 24 |
9 files changed, 231 insertions, 69 deletions
diff --git a/core/src/mill/util/Logger.scala b/core/src/mill/util/Logger.scala index 17c66d27..9b815516 100644 --- a/core/src/mill/util/Logger.scala +++ b/core/src/mill/util/Logger.scala @@ -22,8 +22,8 @@ import ammonite.util.Colors * * Also contains the two forwarded stdout and stderr streams, for code executed * by Mill to use directly. Typically these correspond to the stdout and stderr, - * but when `--show` is used both are forwarded to stderr and stdout is only - * used to display the final `--show` output for easy piping. + * but when `show` is used both are forwarded to stderr and stdout is only + * used to display the final `show` output for easy piping. */ trait Logger { def colored: Boolean diff --git a/docs/cross.md b/docs/cross.md index fe14a23e..f92678d5 100644 --- a/docs/cross.md +++ b/docs/cross.md @@ -17,12 +17,12 @@ This defines three copies of `FooModule`: `"210"`, `"211"` and `"212"`, each of which has their own `suffix` target. You can then run them via ```bash -mill --show foo[2.10].suffix -mill --show foo[2.10].bigSuffix -mill --show foo[2.11].suffix -mill --show foo[2.11].bigSuffix -mill --show foo[2.12].suffix -mill --show foo[2.12].bigSuffix +mill show foo[2.10].suffix +mill show foo[2.10].bigSuffix +mill show foo[2.11].suffix +mill show foo[2.11].bigSuffix +mill show foo[2.12].suffix +mill show foo[2.12].bigSuffix ``` The modules each also have a `millSourcePath` of @@ -66,13 +66,13 @@ takes two parameters instead of one. This creates the following modules each with their own `suffix` target: ```bash -mill --show foo[210,jvm].suffix -mill --show foo[211,jvm].suffix -mill --show foo[212,jvm].suffix -mill --show foo[210,js].suffix -mill --show foo[211,js].suffix -mill --show foo[212,js].suffix -mill --show foo[212,native].suffix +mill show foo[210,jvm].suffix +mill show foo[211,jvm].suffix +mill show foo[212,jvm].suffix +mill show foo[210,js].suffix +mill show foo[211,js].suffix +mill show foo[212,js].suffix +mill show foo[212,native].suffix ``` ## Using Cross Modules from Outside @@ -121,12 +121,12 @@ class BarModule(crossVersion: String) extends Module{ Here, you can run: ```bash -mill --show foo[2.10].suffix -mill --show foo[2.11].suffix -mill --show foo[2.12].suffix -mill --show bar[2.10].bigSuffix -mill --show bar[2.11].bigSuffix -mill --show bar[2.12].bigSuffix +mill show foo[2.10].suffix +mill show foo[2.11].suffix +mill show foo[2.12].suffix +mill show bar[2.10].bigSuffix +mill show bar[2.11].bigSuffix +mill show bar[2.12].bigSuffix ``` diff --git a/docs/extending.md b/docs/extending.md index 9b4656f8..299d8e76 100644 --- a/docs/extending.md +++ b/docs/extending.md @@ -148,5 +148,25 @@ builds, simply publish your code as a library to maven central. For more information, see Ammonite's [Ivy Dependencies documentation](http://ammonite.io/#import$ivy) -## Custom Main Methods +## Evaluator Commands +You can define a command that takes in the current `Evaluator` as an argument, +which you can use to inspect the entire build, or run arbitrary tasks. For +example, here is the `mill.scalalib.GenIdea/idea` command which uses this to +traverse the module-tree and generate an Intellij project config for your build. + +```scala +def idea(ev: Evaluator[Any]) = T.command{ + mill.scalalib.GenIdea( + implicitly, + ev.rootModule, + ev.discover + ) +} +``` + +Many built-in tools are implemented as custom evaluator commands: +[all](intro.html#all), [describe](intro.html#describe), +[resolve](intro.html#resolve), [show](intro.html#show). If you want a way to run Mill +commands and programmatically manipulate the tasks and outputs, you do so with +your own evaluator command. diff --git a/docs/index.md b/docs/index.md index ff26941c..921d4aae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,6 @@ +Mill is your shiny new Scala build tool! Confused by SBT? Frustrated by Maven? +Perplexed by Gradle? Give Mill a try! + Mill is a general purpose build-tool. It has built in support for the [Scala](https://www.scala-lang.org/) programming language, and can serve as a replacement for [SBT](http://www.scala-sbt.org/), but can also be extended to @@ -6,11 +9,11 @@ through external subprocesses. Mill aims for simplicity by re-using concepts you are already familiar with to let you define your project's build. Mill's `build.sc` files are Scala scripts. -If you think SBT is complicated, give Mill a try! -- [Introduction](/mill/intro) -- [Extending](/mill/extending) -- [Tasks](/mill/tasks) -- [Modules](/mill/modules) -- [Cross Building](/mill/cross) -- [Internals](/mill/internals)
\ No newline at end of file + +- [Introduction](intro.html) +- [Extending](extending.html) +- [Tasks](tasks.html) +- [Modules](modules.html) +- [Cross Building](cross.html) +- [Internals](internals.html)
\ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index 3e3778d5..fc33359b 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -56,18 +56,89 @@ $ mill --watch foo.compile $ mill --watch foo.run ``` -### Show Target Output +### Command-line Tools + +Mill comes built in with a small number of useful command-line utilities: + +#### all + +```bash +mill all foo.{compile,run} +mill all "foo.{compile,run}" +mill all foo.compile foo.run +mill all _.compile # run compile for every top-level module +mill all __.compile # run compile for every module +``` + +`all` runs multiple tasks in a single command + +#### resolve + +```bash +mill resolve foo.{compile,run} +mill resolve "foo.{compile,run}" +mill resolve foo.compile foo.run +mill resolve _.compile # list the compile tasks for every top-level module +mill resolve __.compile # list the compile tasks for every module +mill resolve _ # list every top level module or task +mill resolve foo._ # list every task directly within the foo module +mill resolve __ # list every module or task recursively +mill resolve foo._ # list every task recursively within the foo module +``` + +`resolve` lists the tasks that match a particular query, without running them. +This is useful for "dry running" an `mill all` command to see what would be run +before you run them, or to explore what modules or tasks are available from the +command line using `resolve _`, `resolve foo._`, etc. + + +#### describe + +```bash +$ mill describe core.run + +core.run(ScalaModule.scala:211) +Inputs: + core.mainClass + core.runClasspath + core.forkArgs + core.forkEnv +``` + +`describe` is a more verbose version of [resolve](#resolve). In addition to +printing out the name of one-or-more tasks, it also display's it's source +location and a list of input tasks. This is very useful for debugging and +interactively exploring the structure of your build from the command line. + +`describe` also works with the same `_`/`__` wildcard/query syntaxes that +[all](#all)/[resolve](#resolve) do: + + +```bash +mill describe foo.compile +mill describe foo.{compile,run} +mill describe "foo.{compile,run}" +mill describe foo.compile foo.run +mill describe _.compile +mill describe __.compile +mill describe _ +mill describe foo._ +mill describe __ +mill describe foo._ +``` + +#### show By default, Mill does not print out the metadata from evaluating a task. Most people would not be interested in e.g. viewing the metadata related to incremental compilation: they just want to compile their code! However, if you want to inspect the build to debug problems, you can make Mill show you the -metadata output for a task using the `--show` flag: +metadata output for a task using the `show` flag: -You can also ask Mill to display the metadata output of a task using `--show`: +You can also ask Mill to display the metadata output of a task using `show`: ```bash -$ mill --show foo.compile +$ mill show foo.compile { "analysisFile": "/Users/lihaoyi/Dropbox/Github/test/out/foo/compile/dest/zinc", "classes": { @@ -79,12 +150,12 @@ $ mill --show foo.compile This also applies to tasks which hold simple configurable values: ```bash -$ mill --show foo.sources +$ mill show foo.sources [ {"path": "/Users/lihaoyi/Dropbox/Github/test/foo/src"} ] -$ mill --show foo.compileDepClasspath +$ mill show foo.compileDepClasspath [ {"path": ".../org/scala-lang/scala-compiler/2.12.4/scala-compiler-2.12.4.jar"}, {"path": ".../org/scala-lang/scala-library/2.12.4/scala-library-2.12.4.jar"}, @@ -93,18 +164,22 @@ $ mill --show foo.compileDepClasspath ] ``` +`show` is also useful for interacting with Mill from external tools, since the +JSON it outputs is structured and easily parsed & manipulated. + +### IntelliJ Support + +Mill supports IntelliJ by default. Use `mill mill.scalalib.GenIdea/idea` to +generate an IntelliJ project config for your build. + +This also configures IntelliJ to allow easy navigate & code-completion within +your build file itself. + + Any flags passed *before* the name of the task (e.g. `foo.compile`) are given to Mill, while any arguments passed *after* the task are given to the task itself. For example: -```bash -$ mill --watch foo.run -``` - -Makes Mill watch-and-re-evaluate the `foo.run` task, while `mill foo.run ---watch` evaluates `foo.run` once and passes it the `--watch` flag. This matches -the behavior of other executables such as `java` or `python`. - ### The Build Repl ```bash @@ -430,10 +505,10 @@ first run until it's inputs change (in this case, if someone edits the `foo.sources` files which live in `foo/src`. Cached Targets cannot take parameters. -You can print the value of your custom target using `--show`, e.g. +You can print the value of your custom target using `show`, e.g. ```bash -mill run --show lineCount +mill run show lineCount ``` You can define new un-cached Commands using the `T.command{...}` syntax. These @@ -502,8 +577,6 @@ override `compile` and `run` to add additional logging messages. In Mill builds the `override` keyword is optional. -### Publishing Modules - ## Common Project Layouts Above, we have shown how to work with the Mill default Scala module layout. Here @@ -560,10 +633,6 @@ latter of which runs your code on Node.js, which must be pre-installed) `ScalaJSModule` also exposes the `foo.fastOpt` and `foo.fullOpt` tasks for generating the optimized Javascript file. -### Cross Scala-JVM/Scala.js Modules - -### Cross Scala-Version Scala-JVM/JS Modules - ### SBT-Compatible Modules ```scala @@ -622,8 +691,69 @@ foo/ scala-2.12/ ``` -### SBT-Compatible Cross Scala-Version Scala-JVM/JS Modules +### Publishing +```scala +import mill._ +import mill.scalalib._ +object foo extends ScalaModule with PublishModule{ + def scalaVersion = "2.12.4" + def publishVersion = "0.0.1 + def pomSettings = PomSettings( + description = "My first library", + organization = "com.lihaoyi", + url = "https://github.com/lihaoyi/mill", + licenses = Seq( + License("MIT license", "http://www.opensource.org/licenses/mit-license.php") + ), + scm = SCM( + "git://github.com/lihaoyi/mill.git", + "scm:git://github.com/lihaoyi/mill.git" + ), + developers = Seq( + Developer("lihaoyi", "Li Haoyi","https://github.com/lihaoyi") + ) + ) +} +``` + +You can make a module publishable by extending `PublishModule`. + +`PublishModule` then needs you to define a `publishVersion` and `pomSettings`. +The `artifactName` defaults to the name of your module (in this case `foo`) but +can be overriden. The `organization` is defined in `pomSettings`. + +Once you've mixed in `PublishModule`, you can publish your libraries to maven +central via: + +```bash +target/bin/mill mill.scalalib.PublishModule/publishAll \ + lihaoyi:$SONATYPE_PASSWORD \ + $GPG_PASSWORD \ + foo.publishArtifacts +``` + +This uploads them to `oss.sonatype.org` where you can log-in and stage/release +them manually. You can also pass in the `--release true` flag to perform the +staging/release automatically: + +```bash +target/bin/mill mill.scalalib.PublishModule/publishAll \ + lihaoyi:$SONATYPE_PASSWORD \ + $GPG_PASSWORD \ + foo.publishArtifacts \ + --release true +``` +If you want to publish/release multiple modules, you can use the `_` or `__` +wildcard syntax: + +```bash +target/bin/mill mill.scalalib.PublishModule/publishAll \ + lihaoyi:$SONATYPE_PASSWORD \ + $GPG_PASSWORD \ + __.publishArtifacts \ + --release true +``` ## Example Builds @@ -636,7 +766,8 @@ integration tests and examples: - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/acyclic/build.sc#L1) -A small single-module cross-build, with few sources minimal dependencies +A small single-module cross-build, with few sources minimal dependencies, and +wired up for publishing to Maven Central ### Better-Files diff --git a/docs/modules.md b/docs/modules.md index 8bbe6d49..c4dd3f8b 100644 --- a/docs/modules.md +++ b/docs/modules.md @@ -19,7 +19,7 @@ object foo extends mill.Module{ ``` You would be able to run the two targets via `mill foo.bar` or `mill -foo.baz.qux`. You can use `mill --show foo.bar` or `mill --show foo.baz.qux` to +foo.baz.qux`. You can use `mill show foo.bar` or `mill show foo.baz.qux` to make Mill echo out the string value being returned by each Target. The two targets will store their output metadata & files at `./out/foo/bar` and `./out/foo/baz/qux` respectively. @@ -46,11 +46,11 @@ object foo2 extends FooModule{ This would make the following targets available from the command line -- `mill --show foo1.bar` -- `mill --show foo1.baz` -- `mill --show foo2.bar` -- `mill --show foo2.baz` -- `mill --show foo2.qux` +- `mill show foo1.bar` +- `mill show foo1.baz` +- `mill show foo2.bar` +- `mill show foo2.baz` +- `mill show foo2.qux` The built in `mill.scalalib` package uses this to define `mill.scalalib.ScalaModule`, `mill.scalalib.SbtModule` and diff --git a/docs/publishing.md b/docs/publishing.md deleted file mode 100644 index e69de29b..00000000 --- a/docs/publishing.md +++ /dev/null diff --git a/main/src/mill/main/ReplApplyHandler.scala b/main/src/mill/main/ReplApplyHandler.scala index 76ef354f..eac0c7f0 100644 --- a/main/src/mill/main/ReplApplyHandler.scala +++ b/main/src/mill/main/ReplApplyHandler.scala @@ -78,8 +78,8 @@ object ReplApplyHandler{ } pprint.Tree.Lazy(ctx => Iterator( - t.toString, "(", t.ctx.fileName, ":", t.ctx.lineNum.toString, ")", - t.ctx.lineNum.toString, "\n", ctx.applyPrefixColor("Inputs:").toString + t.toString, "(", t.ctx.fileName.split('/').last, ":", t.ctx.lineNum.toString, ")", + "\n", ctx.applyPrefixColor("Inputs:").toString ) ++ t.inputs.iterator.flatMap(rec).map("\n " + _.render) ) } @@ -8,7 +8,15 @@ [patreon-badge]: https://img.shields.io/badge/patreon-sponsor-ff69b4.svg [patreon-link]: https://www.patreon.com/lihaoyi -Your shiny new Scala build tool! +Your shiny new Scala build tool! Confused by SBT? Frustrated by Maven? Perplexed +by Gradle? Give Mill a try! + +If you want to use Mill in your own projects, check out our documentation: + +- [Documentation](http://www.lihaoyi.com/mill/) + +The remainder of this readme is targeted at people who wish to work on Mill's +own codebase. ## How to build and test @@ -42,13 +50,13 @@ There is already a `watch` option that looks for changes on files, e.g.: ``` You can get Mill to show the JSON-structured output for a particular `Target` or -`Command` using the `--show` flag: +`Command` using the `show` flag: ```bash -./target/bin/mill --show core.scalaVersion -./target/bin/mill --show core.compile -./target/bin/mill --show core.assemblyClasspath -./target/bin/mill --show core.test +./target/bin/mill show core.scalaVersion +./target/bin/mill show core.compile +./target/bin/mill show core.assemblyClasspath +./target/bin/mill show core.test ``` Output will be generated into a the `./out` folder. @@ -120,7 +128,7 @@ will run `compile` and `test` targets in `scalalib` module. * Run multiple targets in multiple modules: ```bash -mill --show --all {core,scalalib}.{scalaVersion,scalaBinaryVersion} +mill show --all {core,scalalib}.{scalaVersion,scalaBinaryVersion} ``` will run `scalaVersion` and `scalaBinaryVersion` targets in both `core` and `scalalib` modules. @@ -293,7 +301,7 @@ Each folder currently contains the following files: console during evaluation. - `meta.json`: the cache-key and JSON-serialized return-value of the - `Target`/`Command`. The return-value can also be retrieved via `mill --show + `Target`/`Command`. The return-value can also be retrieved via `mill show core.compile`. Binary blobs are typically not included in `meta.json`, and instead stored as separate binary files in `dest/` which are then referenced by `meta.json` via `PathRef`s |