diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 86263f6678c..c5062427a8e 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -3,15 +3,15 @@ // but we intentionally skim over them and do not go into depth: the focus is // on end user goals and how to achieve them. .Scala Quick Start -* xref:Intro_to_Mill_for_Scala.adoc[] +* xref:Scala_Intro_to_Mill.adoc[] * xref:Scala_Installation_IDE_Support.adoc[] -* xref:Builtin_Commands.adoc[] +* xref:Scala_Builtin_Commands.adoc[] * xref:Scala_Build_Examples.adoc[] * xref:Scala_Module_Config.adoc[] -* xref:Web_Build_Examples.adoc[] +* xref:Scala_Web_Build_Examples.adoc[] .Java Quick Start -* xref:Intro_to_Mill_for_Java.adoc[] +* xref:Java_Intro_to_Mill.adoc[] * xref:Java_Installation_IDE_Support.adoc[] * xref:Java_Builtin_Commands.adoc[] * xref:Java_Build_Examples.adoc[] diff --git a/docs/modules/ROOT/pages/Extending_Mill.adoc b/docs/modules/ROOT/pages/Extending_Mill.adoc index 91601627082..73f816030bf 100644 --- a/docs/modules/ROOT/pages/Extending_Mill.adoc +++ b/docs/modules/ROOT/pages/Extending_Mill.adoc @@ -84,8 +84,8 @@ def idea(ev: Evaluator) = T.command { ---- Many built-in tools are implemented as custom evaluator commands: -xref:Builtin_Commands.adoc#_inspect[inspect], -xref:Builtin_Commands.adoc#_resolve[resolve], -xref:Builtin_Commands.adoc#_show[show]. +xref:Scala_Builtin_Commands.adoc#_inspect[inspect], +xref:Scala_Builtin_Commands.adoc#_resolve[resolve], +xref:Scala_Builtin_Commands.adoc#_show[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/modules/ROOT/pages/Intro_to_Mill_for_Java.adoc b/docs/modules/ROOT/pages/Intro_to_Mill_for_Java.adoc deleted file mode 100644 index e793581a21b..00000000000 --- a/docs/modules/ROOT/pages/Intro_to_Mill_for_Java.adoc +++ /dev/null @@ -1,54 +0,0 @@ - -// Author Notes: -// -// This is the first page a user is expected to land on when learning about -// Mill. It is designed to be a quick, broad overview to get someone started: -// what is Mill, why should they care, and what some simple Mill builds look -// like and how to use them. We intentionally touch shallowly on a lot of -// topics without giving them a proper discussion, since the other pages have -// plenty of space to go in-depth. -// -// By the end of this page, a prospective Mill user should be familiar with -// what Mill is, hopefully have downloaded an example to try out, and be -// interested in learning more about the Mill build tool - -= Introduction to Mill for Java - - -{mill-github-url}[Mill] is your shiny new Java build tool! Mill aims for -simplicity by reusing concepts you are already familiar with, borrowing ideas -from modern tools like https://maven.apache.org/[Maven], https://gradle.org/[Gradle], -https://bazel.build/[Bazel]. Mill lets you build and customize -your projects in a way that's simple, fast, and predictable. - -Mill automates dealing with a lot of common build-tool concerns such as caching, -incremental re-computation, and parallelism. This allows you -to focus your effort on the business logic unique to your build, while letting -Mill take care of all the rest. Mill's caching and parallelism mean it scales well -from small projects to large codebases with hundreds of modules. - -Compared to Maven and Gradle, Mill builds are far more intuitive and easy to read, -write, and debug: - -* **Mill builds are an order of magnitude more concise than Maven pom.xml files**: this makes - them both easy to write and easy to read at a glance - - -include::partial$Intro_to_Mill_Header.adoc[] - - -== Simple Java Module - -include::example/basicjava/1-simple.adoc[] - -== Custom Build Logic - -include::example/basicjava/2-custom-build-logic.adoc[] - -== Multi-Module Project - -include::example/basicjava/3-multi-module.adoc[] - - - -include::partial$Intro_to_Mill_Footer.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/Intro_to_Mill_for_Scala.adoc b/docs/modules/ROOT/pages/Intro_to_Mill_for_Scala.adoc deleted file mode 100644 index 6ee7b10bda2..00000000000 --- a/docs/modules/ROOT/pages/Intro_to_Mill_for_Scala.adoc +++ /dev/null @@ -1,59 +0,0 @@ -// Author Notes: -// -// This is the first page a user is expected to land on when learning about -// Mill. It is designed to be a quick, broad overview to get someone started: -// what is Mill, why should they care, and what some simple Mill builds look -// like and how to use them. We intentionally touch shallowly on a lot of -// topics without giving them a proper discussion, since the other pages have -// plenty of space to go in-depth. -// -// By the end of this page, a prospective Mill user should be familiar with -// what Mill is, hopefully have downloaded an example to try out, and be -// interested in learning more about the Mill build tool - -= Introduction to Mill for Scala - -:page-aliases: index.adoc, Intro_to_Mill.adoc - -{mill-github-url}[Mill] is your shiny new Scala build tool! Mill aims for -simplicity by reusing concepts you are already familiar with, borrowing ideas -from modern tools like https://maven.apache.org/[Maven], https://gradle.org/[Gradle], -https://bazel.build/[Bazel] and https://www.scala-sbt.org/[SBT]. Mill lets you build -and customize your projects in a way that's simple, fast, and predictable. - -Mill automates dealing with a lot of common build-tool concerns such as caching, -incremental re-computation, and parallelism. This allows you -to focus your effort on the business logic unique to your build, while letting -Mill take care of all the rest. Mill's caching and parallelism mean it scales well -from small projects to large codebases with hundreds of modules. - -Compared to SBT and other tools, Mill builds are far more intuitive and easy to read, -write, and debug: - -include::partial$Intro_to_Mill_Header.adoc[] - -The following blog posts discuss some of the fundamental design issues with SBT, and -how Mill attempts to do better: - -- https://www.lihaoyi.com/post/SowhatswrongwithSBT.html[So, what's wrong with SBT?] -- https://www.lihaoyi.com/post/MillBetterScalaBuilds.html[Mill: Better Scala Builds] - -If you are using Mill, you will find the following book by the Author useful in -using Mill and its supporting libraries to the fullest: - -* https://handsonscala.com/[Hands-on Scala Programming] - -== Simple Scala Module - -include::example/basic/1-simple.adoc[] - -== Custom Build Logic - -include::example/basic/2-custom-build-logic.adoc[] - -== Multi-Module Project - -include::example/basic/3-multi-module.adoc[] - - -include::partial$Intro_to_Mill_Footer.adoc[] diff --git a/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc b/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc new file mode 100644 index 00000000000..f1f20f60357 --- /dev/null +++ b/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc @@ -0,0 +1,86 @@ + +// Author Notes: +// +// This is the first page a user is expected to land on when learning about +// Mill. It is designed to be a quick, broad overview to get someone started: +// what is Mill, why should they care, and what some simple Mill builds look +// like and how to use them. We intentionally touch shallowly on a lot of +// topics without giving them a proper discussion, since the other pages have +// plenty of space to go in-depth. +// +// By the end of this page, a prospective Mill user should be familiar with +// what Mill is, hopefully have downloaded an example to try out, and be +// interested in learning more about the Mill build tool + += Introduction to Mill for Java + +:page-aliases: index.adoc, Intro_to_Mill.adoc, Intro_to_Mill_for_Java.adoc + +:language: Java + +include::partial$Intro_to_Mill_Header.adoc[] + +Mill is used to build some real-world Java projects, such as the +https://github.com/swaldman/c3p0[C3P0 JDBC Connection Pool], and +can be used for applications built on top of common Java frameworks like +xref:Java_Web_Build_Examples.adoc#_spring_boot_todomvc_app[Spring Boot] or +xref:Java_Web_Build_Examples.adoc#_micronaut_todomvc_app[Micronaut]. + +Mill borrows ideas from other tools like https://maven.apache.org/[Maven], +https://gradle.org/[Gradle], https://bazel.build/[Bazel], but tries to learn from the +strengths of each tool and improve on their weaknesses. Although Maven and Gradle +are mature widely-used tools, they have fundamental limitations in their design +(https://blog.ltgt.net/maven-is-broken-by-design/[Maven Design], +https://www.bruceeckel.com/2021/01/02/the-problem-with-gradle/[Gradle Design]) that make +them difficult to improve upon incrementally. + +Compared to Maven: + +* **Mill follows Maven's innovation of good built-in defaults**: Mill's built-in + ``JavaModule``s follow Maven's "convention over configuration" style. This provides an + excellent default template that can be used to structure your project without any custom + configuration. + +* **Mill makes customizing the build tool much easier than Maven**. As projects grow, build + grow beyond just compiling a single language: you need custom + code generation, custom linting workflows, custom output artifacts, or support for + additional programming languages. Mill makes doing this yourself easy, so you are not beholden + to third-party plugins that may not exist, be well maintained, or interact well with each other. + +* **Mill automatically caches and parallelizes your build**: This applies not just to the + built-in ``JavaModule``s and tasks that Mill ships with, but also any custom logic the + developer may configure in their Mill build. This maximizes performance and snappiness of + your command-line build workflows, and especially matters in larger codebases where builds + tend to get slow. + +Compared to Gradle: + +* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every + line of configuration in a Mill build is meaningful. e.g. adding a dependency is 1 line in + Mill, like it is in Gradle, and unlike the 5 line `` declaration you find in Maven + +* **Mill helps keep your build understandable**: Unlike Gradle config statements that can + work in mysterious ways, Mill build configuration is done via vanilla methods, objects, + inheritance, and overrides. This means that impact of a Mill config statement is localized, + without "_spooky action at a distance_", and the exact meaning of any config statement is + a single "_jump-to-definition_" away in your IDE. + +Mill build files are written in Scala, but you do not need to have prior experience +in Scala to read or write them. + + +include::partial$Intro_to_Mill_BlogVideo.adoc[] + +== Simple Java Module + +include::example/basicjava/1-simple.adoc[] + +== Custom Build Logic + +include::example/basicjava/2-custom-build-logic.adoc[] + +== Multi-Module Project + +include::example/basicjava/3-multi-module.adoc[] + +include::partial$Intro_to_Mill_Footer.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/Out_Dir.adoc b/docs/modules/ROOT/pages/Out_Dir.adoc index 5865f92d6e1..ec0903dc99e 100644 --- a/docs/modules/ROOT/pages/Out_Dir.adoc +++ b/docs/modules/ROOT/pages/Out_Dir.adoc @@ -90,7 +90,7 @@ feel free to poke around the various `foo.dest/` folders to see what files are being created, or the `foo.json` files to see what is being returned by a particular task. You can also simply delete folders within `out/` if you want to force portions of your project to be -rebuilt, e.g. by deleting the `+out/main/+` or `+out/main/compile.*+` folders, but we strongly encourage you to use the xref:Builtin_Commands.adoc#_clean[`clean` command] instead. +rebuilt, e.g. by deleting the `+out/main/+` or `+out/main/compile.*+` folders, but we strongly encourage you to use the xref:Scala_Builtin_Commands.adoc#_clean[`clean` command] instead. [WARNING] -- diff --git a/docs/modules/ROOT/pages/Builtin_Commands.adoc b/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc similarity index 98% rename from docs/modules/ROOT/pages/Builtin_Commands.adoc rename to docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc index 01cc9b2af36..4793fcc719d 100644 --- a/docs/modules/ROOT/pages/Builtin_Commands.adoc +++ b/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc @@ -1,5 +1,7 @@ = Built-in Commands +:page-aliases: Scala_Builtin_Commands.adoc + Mill comes with a number of useful commands out of the box. These are listed in the Scaladoc: diff --git a/docs/modules/ROOT/pages/Scala_Intro_to_Mill.adoc b/docs/modules/ROOT/pages/Scala_Intro_to_Mill.adoc new file mode 100644 index 00000000000..375a0920205 --- /dev/null +++ b/docs/modules/ROOT/pages/Scala_Intro_to_Mill.adoc @@ -0,0 +1,79 @@ +// Author Notes: +// +// This is the first page a user is expected to land on when learning about +// Mill. It is designed to be a quick, broad overview to get someone started: +// what is Mill, why should they care, and what some simple Mill builds look +// like and how to use them. We intentionally touch shallowly on a lot of +// topics without giving them a proper discussion, since the other pages have +// plenty of space to go in-depth. +// +// By the end of this page, a prospective Mill user should be familiar with +// what Mill is, hopefully have downloaded an example to try out, and be +// interested in learning more about the Mill build tool + += Introduction to Mill for Scala + +:page-aliases: index.adoc, Intro_to_Mill.adoc, Intro_to_Mill_for_Scala.adoc + +:language: Scala + +include::partial$Intro_to_Mill_Header.adoc[] + +Mill is used to build many mainstream Scala projects, such as the +https://github.com/coursier/coursier[Coursier dependency resolver], +https://github.com/VirtusLab/scala-cli[Scala-CLI], and the +https://github.com/com-lihaoyi/Ammonite[Ammonite REPL] + +Mill borrows ideas from other tools like https://maven.apache.org/[Maven], +https://gradle.org/[Gradle], https://bazel.build/[Bazel], or https://www.scala-sbt.org/[SBT]. +It tries to learn from the strengths of each tool, while improving on their weaknesses. + +Compared to SBT: + +* **Mill makes customizing the build yourself much easier**: most of what build tools + do work with files and call subprocesses, and Mill makes doing that yourself easy. + This means you can always make your Mill build do exactly what you want, and are not + beholden to third-party plugins that may not exist, be well maintained, or interact well + with each other. + +* **Mill is much more performant**: SBT has enough overhead that even a dozen + subprojects is enough to slow it down, while Mill can handle hundreds of modules without issue. + Custom tasks in SBT re-execute every time, whereas in Mill they are cached automatically. + Mill's watch-for-changes-and-re-run implementation has much lower latency than SBT's. The + list of ways Mill improves upon SBT's performance is long, and at the command line you + can really feel it + +* **Mill builds are much easier to understand**: Your Mill build is made of bog-standard + ``object``s and ``def``s, rather than SBT's + https://eed3si9n.com/4th-dimension-with-sbt-013/[four-dimensional task matrix]. Your IDE's + "*jump-to-definition*" in Mill actually brings you to the implementation of a task, rather + than an SBT `taskKey` declaration. Customizing things is as simple as writing or overriding + `def`s. The net effect is that despite both tools' build files being written in Scala, + Mill's build files are much easier to understand and maintain. + +For a more detailed dive into the problems with SBT or how Mill improves upon them, check +out the following blog posts: + +- https://www.lihaoyi.com/post/SowhatswrongwithSBT.html[So, what's wrong with SBT?] +- https://www.lihaoyi.com/post/MillBetterScalaBuilds.html[Mill: Better Scala Builds] + +include::partial$Intro_to_Mill_BlogVideo.adoc[] + +If you are using Mill, you will find the following book by the Author useful in +using Mill and its supporting libraries to the fullest: + +* https://handsonscala.com/[Hands-on Scala Programming] + +== Simple Scala Module + +include::example/basic/1-simple.adoc[] + +== Custom Build Logic + +include::example/basic/2-custom-build-logic.adoc[] + +== Multi-Module Project + +include::example/basic/3-multi-module.adoc[] + +include::partial$Intro_to_Mill_Footer.adoc[] diff --git a/docs/modules/ROOT/pages/Web_Build_Examples.adoc b/docs/modules/ROOT/pages/Scala_Web_Build_Examples.adoc similarity index 95% rename from docs/modules/ROOT/pages/Web_Build_Examples.adoc rename to docs/modules/ROOT/pages/Scala_Web_Build_Examples.adoc index b377918b0b1..41af4e4d472 100644 --- a/docs/modules/ROOT/pages/Web_Build_Examples.adoc +++ b/docs/modules/ROOT/pages/Scala_Web_Build_Examples.adoc @@ -1,5 +1,7 @@ = Scala Web Build Examples +:page-aliases: Web_Build_Examples.adoc + This page contains examples of using Mill as a build tool for web-applications. It covers setting up a basic backend server, Todo-MVC app, topics like cache busting, as well as usage of Scala.js both as standalone modules as well as diff --git a/docs/modules/ROOT/pages/The_Mill_Evaluation_Model.adoc b/docs/modules/ROOT/pages/The_Mill_Evaluation_Model.adoc index 39d2c51dfc4..91fdd9f68c3 100644 --- a/docs/modules/ROOT/pages/The_Mill_Evaluation_Model.adoc +++ b/docs/modules/ROOT/pages/The_Mill_Evaluation_Model.adoc @@ -38,8 +38,8 @@ of. In general, we have found that having "two places" to put code - outside of The hard boundary between these two phases is what lets users easily query and visualize their module hierarchy and task graph without running them: using -xref:Builtin_Commands.adoc#inspect[inspect], xref:Builtin_Commands.adoc#plan[plan], -xref:Builtin_Commands.adoc#_visualize[visualize], etc.. This helps keep your +xref:Scala_Builtin_Commands.adoc#inspect[inspect], xref:Scala_Builtin_Commands.adoc#plan[plan], +xref:Scala_Builtin_Commands.adoc#_visualize[visualize], etc.. This helps keep your Mill build discoverable even as the `build.sc` codebase grows. == Caching at Each Layer of the Evaluation Model diff --git a/docs/modules/ROOT/partials/Intro_to_Mill_BlogVideo.adoc b/docs/modules/ROOT/partials/Intro_to_Mill_BlogVideo.adoc new file mode 100644 index 00000000000..8c53832801b --- /dev/null +++ b/docs/modules/ROOT/partials/Intro_to_Mill_BlogVideo.adoc @@ -0,0 +1,14 @@ + +If you're interested in the fundamental ideas behind Mill, rather than the user-facing +benefits discussed above, the following presentation +and companion blog post is a good introduction into what the Mill build tool is +all about: + +- https://www.youtube.com/watch?v=UsXgCeU-ovI&list=PLLMLOC3WM2r6ZFhFfVH74W-sl8LfWtOEc&index=15[Video: A Deep Dive into the Mill Build Tool] +- https://www.lihaoyi.com/post/SoWhatsSoSpecialAboutTheMillScalaBuildTool.html[Blog Post: What's So Special About The Mill Scala Build Tool?] + +The rest of this page contains a quick introduction to getting start with using +Mill to build a simple {language} program. The other pages of this doc-site go into +more depth, with more examples of how to use Mill and more details of how the +Mill build tool works. + diff --git a/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc b/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc index 79360417968..932cfbbe1fd 100644 --- a/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc +++ b/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc @@ -1,26 +1,27 @@ +{mill-github-url}[Mill] is a JVM build tool that supports {language}. Mill aims for performance, +maintainability, and flexibility: +* *Performance*: Mill's xref:Tasks.adoc[build graph] automatically caches and xref:#_parallel_task_execution[parallelizes] build + steps (called "*targets*"), minimizing the amount of work that needs to be done, and + automatically profiling your build so you can optimize it. Even for large codebases with + hundreds of modules, Mill keeps your workflows fast and responsive. -* **Mill builds are easy to extend by non-experts**: anyone can extend a Mill build -with a few lines of code, without needing to learn a complicated plugin framework, -allowing end users the freedom to fit their build logic to their own unique requirements +* *Maintainability*: Mill build targets are self contained without side-effects, making it easy + to trace the data-flow of your build. Mill also provides excellent IDE support + (via xref:{language}_Installation_IDE_Support.adoc#_ide_support[IntelliJ or VSCode]), + letting you use "*jump-to-definition*" to navigate around your build + as easily as any application codebase. This makes maintaining Mill builds + a far easier than the "*guess and grep*" workflows common with other build tools. -* **Mill builds are familiar to anyone who knows programming**: rather than scopes, lifecycles, -or phases, Mill builds on top of objects, methods, inheritance, and overrides: concepts -immediately familiar to any Java programmer +* *Flexibility*: Mill lets you write <>, rather than + error-prone shell scripts, verbose AntRun XML, or complicated external plugins. Mill's + custom targets and modules allow anything from + xref:Tasks.adoc#primitive-tasks[adding simple pipelines], up to + xref:Modules.adoc#_use_case_diy_java_modules[adding entire language toolchains]. + This means Mill does not limit you to what Mill knows how to do, and can be easily + customized to fit what *you* need to get done. -Mill can be xref:Extending_Mill.adoc[extended] -to support any other language or platform via modules or through -external subprocesses. Mill supports a rich ecosystem of -xref:Contrib_Plugins.adoc[] and xref:Thirdparty_Plugins.adoc[]. - -If you prefer a video introduction rather than text, the following presentation -(and companion blog post) is a good introduction into what the Mill build tool is -all about: - -- https://www.youtube.com/watch?v=UsXgCeU-ovI&list=PLLMLOC3WM2r6ZFhFfVH74W-sl8LfWtOEc&index=15[Video: A Deep Dive into the Mill Build Tool] -- https://www.lihaoyi.com/post/SoWhatsSoSpecialAboutTheMillScalaBuildTool.html[Blog Post: What's So Special About The Mill Scala Build Tool?] - -The rest of this page contains a quick introduction to getting start with using -Mill to build a simple program. The other pages of this doc-site go into -more depth, with more examples of how to use Mill and more details of how the -Mill build tool works. +These properties mean that Mill is able to scale well from small projects to +large codebases with hundreds of modules: its performance keeps things snappy, +its maintainability keeps things tidy, and its flexibility supports +the ad-hoc customizations that inevitably appear as projects grow.