tweak-docs

tweak-docs

tweak-docs

tweak-docs

tweak-docs

tweak-readme

tweak-readme

3 files changed, 149 insertions, 30 deletions

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
 
@@ -224,6 +247,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}"
 mill resolve foo.compile foo.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)