From 620a1a092a037a2c46c6d9a4fda0266f53c49ce3 Mon Sep 17 00:00:00 2001 From: Li Haoyi Date: Sun, 18 Feb 2018 00:37:28 -0800 Subject: tweak-docs tweak-docs tweak-docs tweak-docs tweak-docs tweak-readme tweak-readme --- docs/pages/1 - Intro to Mill.md | 90 ++++++++++++++++++++++++++------ docs/pages/2 - Configuring Mill.md | 64 ++++++++++++++++++++++- docs/pages/3 - Common Project Layouts.md | 25 ++++----- 3 files changed, 149 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/pages/1 - Intro to Mill.md b/docs/pages/1 - Intro to Mill.md index cf7a7ff5..3e901dd1 100644 --- a/docs/pages/1 - Intro to Mill.md +++ b/docs/pages/1 - Intro to Mill.md @@ -1,6 +1,7 @@ [Mill](https://github.com/lihaoyi/mill) is your shiny new Scala build tool! -[Confused by SBT](http://www.lihaoyi.com/post/SowhatswrongwithSBT.html)? -Frustrated by Maven? Perplexed by Gradle? Give Mill a try! +[Scared of SBT](http://www.lihaoyi.com/post/SowhatswrongwithSBT.html)? +Melancholy over Maven? Grumbling about Gradle? Baffled by Bazel? Give Mill a +try! Mill aims for simplicity by re-using concepts you are already [familiar with](http://www.lihaoyi.com/post/BuildToolsasPureFunctionalPrograms.html), @@ -81,6 +82,28 @@ The most common **tasks** that Mill can run are cached **targets**, such as re-evaluate unless one of their inputs changes, where-as commands re-run every time. +## Output + +Mill puts all it's output in the top-level `out/` folder. The above commands +would end up in: + +```text +out/ + foo/ + compile/ + run/ + jar/ + assembly/ +``` + +Within the output folder for each task, there's a `meta.json` file containing +the metadata returned by that task, and a `dest/` folder containing any files +that the task generates. For example, `out/foo/compile/dest/` contains the +compiled classfiles, while `out/foo/assembly/dest/` contains the self-contained +assembly with the project's classfiles jar-ed up with all it's dependencies. + +Given a task `foo.bar`, all it's output and results can be found be within it's +respective `out/foo/bar/` folder. ## Multiple Modules @@ -223,6 +246,44 @@ mill all __.compile # run compile for every module ### resolve +```bash +$ mill resolve _ +main +moduledefs +core +scalaworker +scalalib +scalajslib +integration +testRepos +... + +$ mill resolve _.compile + +main.compile +moduledefs.compile +core.compile +scalaworker.compile +scalalib.compile +scalajslib.compile +integration.compile + +$ mill resolve core._ + +core.test +core.compile +core.publishVersion +core.runClasspath +core.testArgs +core.sources +... +``` + +`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. + ```bash mill resolve foo.{compile,run} mill resolve "foo.{compile,run}" @@ -235,12 +296,6 @@ 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 @@ -278,13 +333,20 @@ mill describe foo._ ### show +```bash +$ mill show core.scalaVersion +"2.12.4" +``` + 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` command: -You can also ask Mill to display the metadata output of a task using `show`: +All tasks return values that can be `show`n, not just configuration values. e.g. +`compile` returns that path to the `classes` and `analysisFile` that are +produced by the compilation: ```bash $ mill show foo.compile @@ -296,7 +358,8 @@ $ mill show foo.compile } ``` -This also applies to tasks which hold simple configurable values: +`show` is generally useful as a debugging tool, to see what is going on in your +build: ```bash $ mill show foo.sources @@ -324,11 +387,6 @@ 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: - ## The Build Repl ```bash diff --git a/docs/pages/2 - Configuring Mill.md b/docs/pages/2 - Configuring Mill.md index e6634c75..f7673456 100644 --- a/docs/pages/2 - Configuring Mill.md +++ b/docs/pages/2 - Configuring Mill.md @@ -47,7 +47,8 @@ object foo extends ScalaModule { def ivyDeps = Agg( ivy"com.lihaoyi::upickle:0.5.1", ivy"com.lihaoyi::pprint:0.5.2", - ivy"com.lihaoyi::fansi:0.2.4" + ivy"com.lihaoyi::fansi:0.2.4", + ivy"org.scala-lang:scala-reflect:${scalaVersion()}" ) } ``` @@ -235,6 +236,19 @@ are un-cached and re-evaluate every time you run them, but can take parameters. Their return type needs to be JSON-writable as well, or `(): Unit` if you want to return nothing. +Your custom targets can depend on each other using the `def bar = T{... foo() +...}` syntax, and you can create arbitrarily long chains of dependent targets. +Mill will handle the re-evaluation and caching of the targets' output for you, +and will provide you a `T.ctx().dest` folder for you to use as scratch space or +to store files you want to return. + +Custom targets and commands can contain arbitrary code. Whether you want to +download files (e.g. using `mill.modules.Util.download`), shell-out to Webpack +to compile some Javascript, generate sources to feed into a compiler, or create +some custom jar/zip assembly with the files you want (e.g. using +`mill.modules.Jvm.createJar`), all of these can simply be custom targets with +your code running in the `T{...}` block. + ## Custom Modules ```scala @@ -295,6 +309,52 @@ object foo extends ScalaModule { You can re-define targets and commands to override them, and use `super` if you want to refer to the originally defined task. The above example shows how to -override `compile` and `run` to add additional logging messages. +override `compile` and `run` to add additional logging messages, but you can +also override `ScalaModule#generatedSources` to feed generated code to your +compiler, `ScalaModule#prependShellScript` to make your assemblies executable, +or `ScalaModule#console` to use the Ammonite REPL instead of the normal Scala +REPL. In Mill builds the `override` keyword is optional. + +## Unmanaged Jars + +```scala +// build.sc +import mill._ +import mill.scalalib._ + +object foo extends ScalaModule { + def scalaVersion = "2.12.4" + def unmanagedClasspath = T{ + if (!ammonite.ops.exists(millSourcePath / "lib")) Agg() + else Agg.from(ammonite.ops.ls(millSourcePath / "lib")) + } +} +``` + +You can override `unmanagedClasspath` to point it at any jars you place on the +filesystem, e.g. in the above snippet any jars that happen to live in the +`foo/lib/` folder. + +## Downloading Non-Maven Jars + +```scala +// build.sc +import mill._ +import mill.scalalib._ + +object foo extends ScalaModule { + def scalaVersion = "2.12.4" + def unmanagedClasspath = Agg( + mill.modules.Util.download( + "https://github.com/williamfiset/FastJavaIO/releases/download/v1.0/fastjavaio.jar", + "fastjavaio.jar" + ) + ) +} +``` + +You can also override `unmanagedClasspath` to point it at jars that you want to +download from arbitrary URLs. Note that targets like `unmanagedClasspath` are +cached, so your jar is downloaded only once and re-used indefinitely after that. \ No newline at end of file diff --git a/docs/pages/3 - Common Project Layouts.md b/docs/pages/3 - Common Project Layouts.md index 17d5f95c..9fe4a4fa 100644 --- a/docs/pages/3 - Common Project Layouts.md +++ b/docs/pages/3 - Common Project Layouts.md @@ -1,9 +1,10 @@ -Above, we have shown how to work with the Mill default Scala module layout. Here -we will explore some other common project layouts that you may want in your +## Common Project Layouts +Earlier, we have shown how to work with the Mill default Scala module layout. +Here we will explore some other common project layouts that you may want in your Scala build: -## Cross Scala-Version Modules +### Cross Scala-Version Modules ```scala import mill._ @@ -38,7 +39,7 @@ foo/ Code common to all Scala versions lives in `src`, while code specific to one version lives in `src-x.y`. -## Scala.js Modules +### Scala.js Modules ```scala import mill._ @@ -56,7 +57,7 @@ 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. -## SBT-Compatible Modules +### SBT-Compatible Modules ```scala import mill._ @@ -84,7 +85,7 @@ Useful if you want to migrate an existing project built with SBT without having to re-organize all your files -## SBT-Compatible Cross Scala-Version Modules +### SBT-Compatible Cross Scala-Version Modules ```scala import mill._ @@ -117,7 +118,7 @@ foo/ scala-2.12/ ``` -## Publishing +### Publishing ```scala import mill._ import mill.scalalib._ @@ -188,7 +189,7 @@ Mill comes bundled with example builds for existing open-source projects, as integration tests and examples: -## Acyclic +### Acyclic - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/acyclic/build.sc#L1) @@ -196,7 +197,7 @@ A small single-module cross-build, with few sources minimal dependencies, and wired up for publishing to Maven Central -## Better-Files +### Better-Files - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/better-files/build.sc#L1) @@ -205,21 +206,21 @@ A collection of small modules compiled for a single Scala version. Also demonstrates how to define shared configuration in a `trait`, enable Scala compiler flags, and download artifacts as part of the build. -## Jawn +### Jawn - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/jawn/build.sc#L1) A collection of relatively small modules, all cross-built across the same few versions of Scala. -## Upickle +### Upickle - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/upickle/build.sc#L1) A single cross-platform Scala.js/Scala-JVM module cross-built against multiple versions of Scala, including the setup necessary for publishing to Maven Central -## Ammonite +### Ammonite - [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/ammonite/build.sc#L1) -- cgit v1.2.3