1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
|
## 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.
To declare a module that uses ScalaPB you can extend the `mill.contrib.scalapblib.ScalaPBModule` trait when defining your module.
This creates a Scala module which compiles `.proto` files in the `protobuf` folder of the module with ScalaPB and adds the resulting `.scala` sources to your module's `generatedSources`.
```scala
// build.sc
import mill._, scalalib._, contrib.scalapblib.__
object example extends ScalaPBModule {
def scalaVersion = "2.12.6"
def scalaPBVersion = "0.7.4"
}
```
This defines a project with the following layout:
```
build.sc
example/
src/
protobuf/
resources/
```
#### Configuration options
* scalaPBVersion (mandatory) - The ScalaPB version `String` e.g. `"0.7.4"`
* scalaPBFlatPackage - A `Boolean` option which determines whether the `.proto` file name should be appended as the final segment of the package name in the generated sources.
* scalaPBJavaConversions - A `Boolean` option which determines whether methods for converting between the generated Scala classes and the Protocol Buffers Java API classes should be generated.
* scalaPBGrpc - A `Boolean` option which determines whether [grpc](https://grpc.io) stubs should be generated.
* scalaPBSingleLineToProtoString - A `Boolean` option which determines whether the generated `.toString` methods should use a single line format.
If you'd like to configure the options that are passed to the ScalaPB compiler directly, you can override the `scalaPBOptions` task, for example:
```scala
object example extends ScalaPBModule {
def scalaVersion = "2.12.6"
def scalaPBVersion = "0.7.4"
override def scalaPBOptions = "flat_package,java_conversions"
}
```
### TestNG
Provides support for [TestNG](https://testng.org/doc/index.html).
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
* 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.
* 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`)
* 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"
* `def twirlAdditionalImports: Seq[String] = Nil` - the additional imports that will be added by twirl compiler to the top of all templates
* `def twirlConstructorAnnotations: Seq[String] = Nil` - annotations added to the generated classes' constructors (note it only applies to templates with `@this(...)` constructors)
* `def twirlCodec = Codec(Properties.sourceEncoding)` - the codec used to generate the files (the default is the same sbt plugin uses)
* `def twirlInclusiveDot: Boolean = false`
#### 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) }
}
```
To add additional imports to all of the twirl templates:
```scala
object app extends ScalaModule with TwirlModule {
def twirlVersion = "1.3.15"
override def twirlAdditionalImports = Seq("my.additional.stuff._", "my.other.stuff._")
def generatedSources = T{ Seq(compileTwirl().classes) }
}
```
as the result all templates will get this line at the top:
```scala
@import "my.additional.stuff._"
@import "my.other.stuff._"
```
Besides that, twirl compiler has default imports, at the moment these:
```scala
Seq(
"_root_.play.twirl.api.TwirlFeatureImports._",
"_root_.play.twirl.api.TwirlHelperImports._",
"_root_.play.twirl.api.Html",
"_root_.play.twirl.api.JavaScript",
"_root_.play.twirl.api.Txt",
"_root_.play.twirl.api.Xml"
)
```
These imports will always be added to every template. You don't need to list them if you override `twirlAdditionalImports`.
#### Example
There's an [example project](https://github.com/lihaoyi/cask/tree/master/example/twirl)
### Play Framework
Play framework routes generation support.
To declare a module that needs to generate Play Framework routes, you must mix-in the
`mill.playlib.routesModule` trait when defining your module.
```scala
import $ivy.`com.lihaoyi::mill-contrib-playlib:0.3.3`, mill.playlib._
object app extends RouterModule {
// ...
}
```
#### Configuration options
* `def playVersion: T[String]` (mandatory) - The version of play to use to compile the routes file.
* `def scalaVersion: T[String]` - The scalaVersion in use in your project.
* `def conf: Sources` - The directory which contains your route files. (Defaults to : `routes/` )
* `def routesAdditionalImport: Seq[String]` - Additional imports to use in the generated routers. (Defaults to `Seq("controllers.Assets.Asset", "play.libs.F")`
* `def generateForwardsRouter: Boolean = true` - Enables the forward router generation.
* `def generateReverseRouter: Boolean = true` - Enables the reverse router generation.
* `def namespaceReverseRouter: Boolean = false` - Enables the namespacing of reverse routers.
* `def generatorType: RouteCompilerType = RouteCompilerType.InjectedGenerator` - The routes compiler type, one of RouteCompilerType.InjectedGenerator or RouteCompilerType.StaticGenerator
#### Details
The following filesystem layout is expected by default:
```text
.
├── app
│ └── routes
│ └── routes
└── build.sc
```
`RouterModule` adds the `compileRouter` task to the module:
```
mill app.compileRouter
```
(it will be automatically run whenever you compile your module)
This task will compile `routes` templates into the `out/app/compileRouter/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 RouterModule {
def playVersion= T{"2.7.0"}
def scalaVersion= T{"2.12.8"}
}
```
To add additional imports to all of the routes:
```scala
object app extends ScalaModule with RouterModule {
def playVersion = "2.7.0"
override def routesAdditionalImport = Seq("my.additional.stuff._", "my.other.stuff._")
}
```
If you want to use playframework's default of storing the routes in `conf/` you can do the
follwing:
```scala
object app extends ScalaModule with RouterModule {
def playVersion = "2.7.0"
override def routesAdditionalImport = Seq("my.additional.stuff._", "my.other.stuff._")
override def routes = T.sources{ millSourcePath / 'conf }
}
```
which will work with the following directory structure:
```text
.
├── app
│ └── conf
│ └── routes
└── build.sc
```
## 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 mill._, mill.scalalib._
import $ivy.`de.tototec::de.tobiasroeser.mill.osgi:0.0.5`
import de.tobiasroeser.mill.osgi._
object project extends ScalaModule with OsgiBundleModule {
def bundleSymbolicName = "com.example.project"
def osgiHeaders = T{ super.osgiHeaders().copy(
`Export-Package` = Seq("com.example.api"),
`Bundle-Activator` = Some("com.example.internal.Activator")
)}
// other settings ...
}
```
### 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
```
|