Merge branch 'master' of github.com:lihaoyi/mill

3 files changed, 337 insertions, 77 deletions

diff --git a/docs/pages/4 - Tasks.md b/docs/pages/4 - Tasks.md
index 6c7737e0..e8a1c94c 100644
--- a/docs/pages/4 - Tasks.md
+++ b/docs/pages/4 - Tasks.md
@@ -199,6 +199,9 @@ task are streamed to standard out/error as you would expect, but each task's
 specific output is also streamed to a log file on disk, e.g. `out/run/log` or
 `out/classFiles/log` for you to inspect later.
 
+Messages logged with `log.debug` appear by default only in the log files.
+You can use the `--debug` option when running mill to show them on the console too.
+
 ### mill.util.Ctx.Env
 
 - `T.ctx().env`
diff --git a/docs/pages/7 - Extending Mill.md b/docs/pages/7 - Extending Mill.md
index 2eb7c93b..2e59dfe3 100644
--- a/docs/pages/7 - Extending Mill.md
+++ b/docs/pages/7 - Extending Mill.md
@@ -176,7 +176,6 @@ def idea(ev: Evaluator) = T.command {
 ```
 
 Many built-in tools are implemented as custom evaluator commands:
-[all](intro.html#all), [inspect](intro.html#inspect),
-[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.
+[all](http://www.lihaoyi.com/mill/#all), [inspect](http://www.lihaoyi.com/mill/#inspect),
+[resolve](http://www.lihaoyi.com/mill/#resolve), [show](http://www.lihaoyi.com/mill/#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/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md
index f6c9cc7b..cd02f2c2 100644
--- a/docs/pages/9 - Contrib Modules.md
+++ b/docs/pages/9 - Contrib Modules.md
@@ -1,5 +1,36 @@
 ## Contrib Modules
 
+### BuildInfo
+
+Generate scala code from your buildfile.
+This plugin generates a single object containing information from your build.
+
+To declare a module that uses BuildInfo you must extend the `mill.contrib.BuildInfo` trait when defining your module.
+
+Quickstart:
+```scala
+object project extends BuildInfo {
+  val name = "poject-name"
+  def  buildInfoMembers: T[Map[String, String]] = T {
+    Map(
+      "name" -> name),
+      "scalaVersion" -> scalaVersion()
+    )
+  }
+}
+```
+
+#### Configuration options
+
+* `def buildInfoMembers: T[Map[String, String]]`
+  The map containing all member names and values for the generated info object.
+
+* `def buildInfoObjectName: String`, default: `BuildInfo`
+  The name of the object which contains all the members from `buildInfoMembers`.
+
+* `def buildInfoPackageName: Option[String]`, default: `None`
+  The package name of the object.
+
 ### ScalaPB
 
 This module allows [ScalaPB](https://scalapb.github.io) to be used in Mill builds. ScalaPB is a [Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler plugin that generates Scala case classes, encoders and decoders for protobuf messages.
@@ -50,96 +81,323 @@ object example extends ScalaPBModule {
 }
 ```
 
-### BuildInfo
+### TestNG
 
-Generate scala code from your buildfile.  
-This plugin generates a single object containing information from your build.
-  
-To declare a module that uses BuildInfo you must extend the `mill.contrib.BuildInfo` trait when defining your module.
+Provides support for [TestNG](https://testng.org/doc/index.html).
 
-Quickstart:
-  ```scala
-  object project extends BuildInfo {
-    val name = "poject-name"
-    def  buildInfoMembers: T[Map[String, String]] = T {
-      Map(
-        "name" -> name),
-        "scalaVersion" -> scalaVersion()
-      )
-    }
+To use TestNG as test framework, you need to add it to the `TestModule.testFrameworks` property.
+
+```scala
+object project extends ScalaModule {
+  object test extends Tests{
+    def testFrameworks = Seq("mill.testng.TestNGFramework")
   }
-  ```
-  
+}
+```
+
+### Tut
+
+This module allows [Tut](https://tpolecat.github.io/tut) to be used in Mill builds. Tut is a documentation tool which compiles and evaluates Scala code in documentation files and provides various options for configuring how the results will be displayed in the compiled documentation.
+
+To declare a module that uses Tut you can extend the `mill.contrib.tut.TutModule` trait when defining your module.
+
+This creates a Scala module which compiles markdown, HTML and `.txt` files in the `tut` folder of the module with Tut.
+
+By default the resulting documents are simply placed in the Mill build output folder but they can be placed elsewhere by overriding the `tutTargetDirectory` task.
+
+```scala
+// build.sc
+import mill._, scalalib._, contrib.tut.__
+
+object example extends TutModule {
+  def scalaVersion = "2.12.6"
+  def tutVersion = "0.6.7"
+}
+```
+
+This defines a project with the following layout:
+
+```
+build.sc
+example/
+    src/
+    tut/
+    resources/
+```
+
+In order to compile documentation we can execute the `tut` task in the module:
+
+```
+sh> mill example.tut
+```
+
 #### Configuration options
 
-* `def buildInfoMembers: T[Map[String, String]]`  
-  The map containing all member names and values for the generated info object.
+* tutSourceDirectory - This task determines where documentation files must be placed in order to be compiled with Tut. By default this is the `tut` folder at the root of the module.
 
-* `def buildInfoObjectName: String`, default: `BuildInfo`  
-  The name of the object which contains all the members from `buildInfoMembers`.
+* tutTargetDirectory - A task which determines where the compiled documentation files will be placed. By default this is simply the Mill build's output folder for the `tutTargetDirectory` task but this can be reconfigured so that documentation goes to the root of the module (e.g. `millSourcePath`) or to a dedicated folder (e.g. `millSourcePath / 'docs`)
 
-* `def buildInfoPackageName: Option[String]`, default: `None`  
-  The package name of the object.
+* tutClasspath - A task which determines what classpath is used when compiling documentation. By default this is configured to use the same inputs as the `runClasspath`, except for using `tutIvyDeps` rather than the module's `ivyDeps`.
+
+* tutScalacPluginIvyDeps - A task which determines the scalac plugins which will be used when compiling code examples with Tut. The default is to use the `scalacPluginIvyDeps` for the module.
+
+* tutNameFilter - A `scala.util.matching.Regex` task which will be used to determine which files should be compiled with tut. The default pattern is as follows: `.*\.(md|markdown|txt|htm|html)`.
+
+* tutScalacOptions - The scalac options which will be used when compiling code examples with Tut. The default is to use the `scalacOptions` for the module but filtering out options which are problematic in the REPL, e.g. `-Xfatal-warnings`, `-Ywarn-unused-imports`.
+
+* tutVersion - The version of Tut to use.
+
+* tutIvyDeps - A task which determines how to fetch the Tut jar file and all of the dependencies required to compile documentation for the module and returns the resulting files.
+
+* tutPluginJars - A task which performs the dependency resolution for the scalac plugins to be used with Tut.
+
+### Twirl
+
+Twirl templates support.
+
+To declare a module that needs to compile twirl templates you must extend the `mill.twirllib.TwirlModule` trait when defining your module. 
+Also note that twirl templates get compiled into scala code, so you also need to extend `ScalaModule`.
+ 
+```scala
+import $ivy.`com.lihaoyi::mill-contrib-twirllib:0.3.2`,  mill.twirllib._
+object app extends ScalaModule with TwirlModule {
+
+} 
+``` 
+
+#### Configuration options
+
+* ` def twirlVersion: T[String]` (mandatory) - the version of the twirl compiler to use, like "1.3.15"
+
+#### Details
+
+The following filesystem layout is expected:
+
+```text
+build.sc
+app/
+    views/
+        view1.scala.html
+        view2.scala.html
+```
+
+`TwirlModule` adds the `compileTwirl` task to the module:
+```
+mill app.compileTwirl
+```
+
+(it will be automatically run whenever you compile your module)
+
+This task will compile `*.scala.html` templates (and others, like `*.scala.txt`) into the `out/app/compileTwirl/dest` 
+directory. This directory must be added to the generated sources of the module to be compiled and made accessible from the rest of the code:
+```scala
+object app extends ScalaModule with TwirlModule {
+  def twirlVersion = "1.3.15"
+  def generatedSources = T{ Seq(compileTwirl().classes) }
+}
+``` 
 
+#### Caveats
 
-### Other Mill Plugins
+There is a couple of caveats, to be aware of, as of now (in `v0.3.2`).
 
-- [ensime](https://github.com/yyadavalli/mill-ensime "mill-ensime")
+##### Packages 
+First, if you structure your twirl templates into packages, like this:
+```text
+build.sc
+app/
+    src/hello/
+        Main.scala
+    views/
+        hello/
+            another/ 
+                view1.scala.html
+                view2.scala.html
+```
 
-  Create an [.ensime](http://ensime.github.io/ "ensime") file for your build.
-  
-  Quickstart:
-  ```scala
-  import $ivy.`fun.valycorp::mill-ensime:0.0.1`
-  ```
-  ```sh
-  sh> mill fun.valycorp.mill.GenEnsime/ensimeConfig
-  ```
-  
-- [dgraph](https://github.com/ajrnz/mill-dgraph "mill-dgraph")
+the generated sources in the `out` directory will look like this:
+```text
+build.sc
+out/app/compileTwirl/dest/
+    hello/
+      another/
+        html/
+          view1.template.scala
+          view2.template.scala
+```
 
-  Show transitive dependencies of your build in your browser.
-  
-  Quickstart:
-  ```scala
-  import $ivy.`com.github.ajrnz::mill-dgraph:0.2.0`
-  ```
-  ```sh
-  sh> mill plugin.dgraph.browseDeps(proj)()
-  ```
+Looking at the `mill show app.compileTwirl` in this setup shows this:
+```
+{
+    ...
+    "classes": "ref: ... : .../out/app/compileTwirl/dest/html"
+}
+```
 
-- [publishM2](https://github.com/lefou/mill-publishM2 "mill-publishM2")
+Basically it means that currently `TwirlModule` expects all templates to be html and with no packages.
+So adding this directly to the generated sources will not exactly work as expected (as there might not even be a `out/app/compileTwirl/dest/html` directory
+at all, unless you have templates in the default package).
 
-  Mill plugin to publish artifacts into a local Maven repository.
+The workaround is simple, though:
+```scala
+object app extends ScalaModule with TwirlModule {
+  def twirlVersion = "1.3.15"
+  override def generatedSources = T{
+    val classes = compileTwirl().classes
+    Seq(classes.copy(path = classes.path / up)) // we just move one dir up
+  }
+}
+``` 
+
+This should cover the problem with templates under packages, and also should make other-than-html 
+templates available as well.
+
+##### Default imports
 
-  Quickstart:
+Another problem is with some default imports that the twirl sbt plugin assumes, but it seems not to work with `TwirlModule`.
 
-  Just mix-in the `PublishM2Module` into your project.
-  `PublishM2Module` already extends mill's built-in `PublishModule`.
+If you reference `Html` in your templates, like
+
+```scala
+// wrapper.scala.html
+@(content: Html)
+<div class="wrapper">
+  @content
+</div>
+```
 
-  File: `build.sc`
-  ```scala
-  import mill._, scalalib._, publish._
+the template will not compile. You'll need to add this import:
+```
+@import play.twirl.api._
+```
 
-  import $ivy.`de.tototec::de.tobiasroeser.mill.publishM2:0.0.1`
-  import de.tobiasroeser.mill.publishM2._
+in the template that uses twirl classes.
 
-  object project extends PublishModule with PublishM2Module {
-    // ...
+Another one is `@defining`, which might be used like this:
+```
+@defining({
+  val calculatedClass = {
+    // do some calculations here
   }
-  ```
-
-  Publishing to default local Maven repository
-
-  ```
-  > mill project.publishM2Local
-  [40/40] project.publishM2Local
-  Publishing to /home/user/.m2/repository
-  ```
-
-  Publishing to custom local Maven repository
-  ```
-  > mill project.publishM2Local /tmp/m2repo
-  [40/40] project.publishM2Local
-  Publishing to /tmp/m2repo
-  ```
+  calculatedClass
+}) { calculatedClass =>
+    <div class="@calculatedClass">stuff 1</div>
+    <div class="@calculatedClass">stuff 2</div>
+}
+```
+
+You'll need this import:
+```scala
+@import play.twirl.api.TwirlFeatureImports._
+```
+
+At some point `TwirlModule` might get support for the additional "default" imports, which will make this much easier, 
+but right now it is unimplemented
+
+```scala
+  // REMIND currently it's not possible to override these default settings
+  private def twirlAdditionalImports: Seq[String] = Nil
+```
+
+#### Example
+There's an [example project](https://github.com/lihaoyi/cask/tree/master/example/twirl)
+
+
+
+## Thirdparty Mill Plugins
+
+### DGraph
+
+Show transitive dependencies of your build in your browser.
+
+Project home: https://github.com/ajrnz/mill-dgraph
+
+#### Quickstart
+
+```scala
+import $ivy.`com.github.ajrnz::mill-dgraph:0.2.0`
+```
+
+```sh
+sh> mill plugin.dgraph.browseDeps(proj)()
+```
+
+### Ensime
+
+Create an [.ensime](http://ensime.github.io/ "ensime") file for your build.
+
+Project home: https://github.com/yyadavalli/mill-ensime
+
+#### Quickstart
+
+```scala
+import $ivy.`fun.valycorp::mill-ensime:0.0.1`
+```
+
+```sh
+sh> mill fun.valycorp.mill.GenEnsime/ensimeConfig
+```
+
+### OSGi
+
+Produce OSGi Bundles with mill.
+
+Project home: https://github.com/lefou/mill-osgi
+
+#### Quickstart
+
+```scala
+import $ivy.`de.tototec::de.tobiasroeser.mill.osgi:0.0.2`
+import de.tobiasroeser.mill.osgi._
+
+object project extends ScalaModule with OsgiBundleModule {
+
+  def bundleSymbolicName = "com.example.project"
+
+  def osgiHeaders = T{ osgiHeaders().copy(
+    `Export-Package`   = Seq("com.example.api"),
+    `Bundle-Activator` = Some("com.example.internal.Activator")
+  )}
+
+}
+```
+
+
+### PublishM2
+
+Mill plugin to publish artifacts into a local Maven repository.
+
+Project home: https://github.com/lefou/mill-publishM2
+
+#### Quickstart
+
+Just mix-in the `PublishM2Module` into your project.
+`PublishM2Module` already extends mill's built-in `PublishModule`.
+
+File: `build.sc`
+```scala
+import mill._, scalalib._, publish._
+
+import $ivy.`de.tototec::de.tobiasroeser.mill.publishM2:0.0.1`
+import de.tobiasroeser.mill.publishM2._
+
+object project extends PublishModule with PublishM2Module {
+  // ...
+}
+```
+
+Publishing to default local Maven repository
+
+```bash
+> mill project.publishM2Local
+[40/40] project.publishM2Local
+Publishing to /home/user/.m2/repository
+```
+
+Publishing to custom local Maven repository
+
+```bash
+> mill project.publishM2Local /tmp/m2repo
+[40/40] project.publishM2Local
+Publishing to /tmp/m2repo
+```