From 3075356a2b6f6a10c43a32e6413fcbd41b4d0822 Mon Sep 17 00:00:00 2001 From: Li Haoyi Date: Sat, 10 Feb 2018 09:49:37 -0800 Subject: Set theme jekyll-theme-leap-day --- docs/example.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 docs/example.md (limited to 'docs/example.md') diff --git a/docs/example.md b/docs/example.md new file mode 100644 index 00000000..04ebfc7c --- /dev/null +++ b/docs/example.md @@ -0,0 +1,220 @@ + +## Common Project Layouts + +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 +Scala build: + +### Cross Scala-Version Modules + +```scala +import mill._ +import mill.scalalib._ +object foo extends Cross[FooModule]("2.10.6", "2.11.11", "2.12.4") +class FooModule(val crossScalaVersion: String) extends CrossScalaModule{ + ... +} +``` + +Mill provides a `CrossScalaModule` template, which can be used with `Cross` to +cross-build Scala modules across different versions of Scala. The default +configuration for `CrossScalaModule` expects a filesystem layout as follows: + +```text +build.sc +foo/ + src/ + src-2.10/ + src-2.11/ + src-2.12/ + test/ + src/ + src-2.10/ + src-2.11/ + src-2.12/ +``` + +Code common to all Scala versions lives in `src`, while code specific to one +version lives in `src-x.y`. + +### Scala.js Modules + +```scala +import mill._ +import mill.scalajslib._ + +object foo extends ScalaJSModule { + def scalaVersion = "2.12.4" + def scalaJSVersion = "0.6.22" +} +``` + +`ScalaJSModule` is a variant of `ScalaModule` that builds your code using +Scala.js. In addition to the standard `foo.compile` and `foo.run` commands (the +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 + +```scala +import mill._ +import mill.scalalib._ + +object foo extends SbtModule { + def scalaVersion = "2.12.4" +} +``` + +These are basically the same as normal `ScalaModule`s, but configured to follow +the SBT project layout: + +```text +build.sc +foo/ + src/ + main/ + scala/ + test/ + scala/ +``` + +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 + +```scala +import mill._ +import mill.scalalib._ +object foo extends Cross[FooModule]("2.10.6", "2.11.11", "2.12.4") +class FooModule(val crossScalaVersion: String) extends CrossSbtModule{ + ... +} +``` + +A `CrossSbtModule` is a version of `CrossScalaModule` configured with the SBT +project layout: + +```text +build.sc +foo/ + src/ + main/ + scala/ + scala-2.10/ + scala-2.11/ + scala-2.12/ + test/ + scala/ + scala-2.10/ + scala-2.11/ + scala-2.12/ +``` + +### 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 + +Mill comes bundled with example builds for existing open-source projects, as +integration tests and examples: + + +### Acyclic + +- [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, and +wired up for publishing to Maven Central + + +### Better-Files + +- [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/better-files/build.sc#L1) + +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 + +- [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. + + +### Ammonite + +- [Mill Build](https://github.com/lihaoyi/mill/blob/master/integration/test/resources/ammonite/build.sc#L1) + +A relatively complex build with numerous submodules, some cross-built across +Scala major versions while others are cross-built against Scala minor versions. + +Also demonstrates how to pass one module's compiled artifacts to the +`run`/`test` commands of another, via their `forkEnv`. \ No newline at end of file -- cgit v1.2.3