From 081d699d76f57341b2589dc839b8e8e4542cfece Mon Sep 17 00:00:00 2001 From: Li Haoyi Date: Sat, 14 Sep 2024 09:17:48 +0800 Subject: [PATCH] Integrate kotlin example into docs (#3544) * Added `Kotlin_Intro_to_Mill.adoc`, `Kotlin_Installation_IDE_Support.adoc`, `Kotlin_Builtin_Commands.adoc` pages * Fixed an issue with inherited example adoc pages not rendering correctly since https://github.com/com-lihaoyi/mill/pull/3398 --- docs/modules/ROOT/nav.adoc | 4 ++ .../ROOT/pages/Java_Builtin_Commands.adoc | 9 --- .../ROOT/pages/Java_Intro_to_Mill.adoc | 56 +----------------- .../ROOT/pages/Kotlin_Builtin_Commands.adoc | 3 + .../Kotlin_Installation_IDE_Support.adoc | 3 + .../ROOT/pages/Kotlin_Intro_to_Mill.adoc | 48 ++++++++++++++++ .../ROOT/pages/Scala_Builtin_Commands.adoc | 8 --- .../Intro_Maven_Gradle_Comparison.adoc | 57 +++++++++++++++++++ example/package.mill | 10 ++++ .../basic/4-builtin-commands/build.mill | 9 +++ 10 files changed, 135 insertions(+), 72 deletions(-) create mode 100644 docs/modules/ROOT/pages/Kotlin_Builtin_Commands.adoc create mode 100644 docs/modules/ROOT/pages/Kotlin_Installation_IDE_Support.adoc create mode 100644 docs/modules/ROOT/pages/Kotlin_Intro_to_Mill.adoc create mode 100644 docs/modules/ROOT/partials/Intro_Maven_Gradle_Comparison.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 218fff740f3..12fd844d1c5 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -27,6 +27,10 @@ * xref:Scala_Web_Examples.adoc[] * xref:Case_Study_Mill_vs_SBT.adoc[] +.xref:Kotlin_Intro_to_Mill.adoc[] +* xref:Kotlin_Installation_IDE_Support.adoc[] +* xref:Kotlin_Builtin_Commands.adoc[] + // This section is all about developing a deeper understanding of specific // topics in Mill. This is the opposite of `Quick Start` above: while we touch // on some end-user use cases, it is only to motivate the Mill features that we diff --git a/docs/modules/ROOT/pages/Java_Builtin_Commands.adoc b/docs/modules/ROOT/pages/Java_Builtin_Commands.adoc index 28b04476ac3..58d0ae17609 100644 --- a/docs/modules/ROOT/pages/Java_Builtin_Commands.adoc +++ b/docs/modules/ROOT/pages/Java_Builtin_Commands.adoc @@ -1,12 +1,3 @@ = Built-in Commands -Mill comes with a number of useful commands out of the box. These are listed -in the Scaladoc: - -* {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule] - -Mill's built-in commands are typically not directly related to building your -application code, but instead are utilities that help you understand and work -with your Mill build. - include::example/javalib/basic/4-builtin-commands.adoc[] diff --git a/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc b/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc index 6bfc0792c63..fe9c03ac93b 100644 --- a/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc +++ b/docs/modules/ROOT/pages/Java_Intro_to_Mill.adoc @@ -32,61 +32,7 @@ can be used for applications built on top of common Java frameworks like xref:Java_Web_Examples.adoc#_spring_boot_todomvc_app[Spring Boot] or xref:Java_Web_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. - -xref:Case_Study_Mill_vs_Maven.adoc[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. Small mill - projects require minimal effort to get started, and larger Mill projects have a consistent - structure building on these defaults. - -* **Mill makes customizing the build tool much easier than Maven**. Projects usually - grow beyond just compiling a single language: needing custom - code generation, linting workflows, output artifacts, or support for - additional 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**: Not just the - built-in tasks that Mill ships with, but also any custom tasks or modules. - This maximizes performance and snappiness of - your command-line build workflows, and especially matters in larger codebases where builds - tend to get slow: a Maven `clean install` taking over a minute might take just a - few seconds in Mill. - -xref:Case_Study_Mill_vs_Gradle.adoc[Compared to Gradle]: - -* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every - line 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. - Skimming and understanding a 100-line Mill `build.mill` file is - often much easier than skimming the equivalent 500-line Maven `pom.xml`. - -* **Mill builds more performant**: Although both Mill and Gradle automatically cache and - parallelize your build, Mill does so with much less fixed overhead, resulting in 2-3x - speedups in common command-line workflows. This means less time waiting for your build - tool, and more time focusing on the things that really matter to your project. - -* **Mill enforces best practices by default**. All Mill tasks are cached by default, even - custom tasks. All Mill tasks write their output to disk xref:Out_Dir.adoc[a - standard place]. All task inter-dependencies are automatically captured, without - needing manual annotation. All Mill builds are incremental, not just tasks but also - xref:The_Mill_Evaluation_Model.adoc#_caching_at_each_layer_of_the_evaluation_model[configuration - and other phases]. Where Gradle requires considerable - https://docs.gradle.org/current/userguide/incremental_build.html[effort and expertise] - to maintain your build, Mill automates it so the - easiest thing to do is almost always the right thing to do. - -Mill build files are written in Scala, but you do not need to have prior experience -in Scala to read or write them. Like Gradle Groovy or Maven XML, it's easy to learn -enough Scala for Mill without needing to become an expert in the language. - +include::partial$Intro_Maven_Gradle_Comparison.adoc[] include::partial$Intro_to_Mill_BlogVideo.adoc[] diff --git a/docs/modules/ROOT/pages/Kotlin_Builtin_Commands.adoc b/docs/modules/ROOT/pages/Kotlin_Builtin_Commands.adoc new file mode 100644 index 00000000000..acc4af7cffe --- /dev/null +++ b/docs/modules/ROOT/pages/Kotlin_Builtin_Commands.adoc @@ -0,0 +1,3 @@ += Built-in Commands + +include::example/kotlinlib/basic/4-builtin-commands.adoc[] diff --git a/docs/modules/ROOT/pages/Kotlin_Installation_IDE_Support.adoc b/docs/modules/ROOT/pages/Kotlin_Installation_IDE_Support.adoc new file mode 100644 index 00000000000..951ea10b6bf --- /dev/null +++ b/docs/modules/ROOT/pages/Kotlin_Installation_IDE_Support.adoc @@ -0,0 +1,3 @@ += Installation and IDE Support + +include::partial$Installation_IDE_Support.adoc[] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/Kotlin_Intro_to_Mill.adoc b/docs/modules/ROOT/pages/Kotlin_Intro_to_Mill.adoc new file mode 100644 index 00000000000..3166425849a --- /dev/null +++ b/docs/modules/ROOT/pages/Kotlin_Intro_to_Mill.adoc @@ -0,0 +1,48 @@ + +// 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 Kotlin + +++++ + +++++ + +:language: Kotlin + +include::partial$Intro_to_Mill_Header.adoc[] + + +include::partial$Intro_Maven_Gradle_Comparison.adoc[] + +Mill's Kotlin support originated as the third-party plugin +https://github.com/lefou/mill-kotlin[lefou/mill-kotlin], which was later included with +the main Mill codebase. + +include::partial$Intro_to_Mill_BlogVideo.adoc[] + +== Simple Kotlin Module + +include::example/kotlinlib/basic/1-simple.adoc[] + +== Custom Build Logic + +include::example/kotlinlib/basic/2-custom-build-logic.adoc[] + +== Multi-Module Project + +include::example/kotlinlib/basic/3-multi-module.adoc[] + +include::partial$Intro_to_Mill_Footer.adoc[] diff --git a/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc b/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc index dcacccbf1b1..c21d20dc4e0 100644 --- a/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc +++ b/docs/modules/ROOT/pages/Scala_Builtin_Commands.adoc @@ -2,14 +2,6 @@ :page-aliases: Scala_Builtin_Commands.adoc -Mill comes with a number of useful commands out of the box. These are listed -in the Scaladoc: - -* {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule] - -Mill's built-in commands are typically not directly related to building your -application code, but instead are utilities that help you understand and work -with your Mill build. include::example/scalalib/basic/4-builtin-commands.adoc[] diff --git a/docs/modules/ROOT/partials/Intro_Maven_Gradle_Comparison.adoc b/docs/modules/ROOT/partials/Intro_Maven_Gradle_Comparison.adoc new file mode 100644 index 00000000000..41aaacff27d --- /dev/null +++ b/docs/modules/ROOT/partials/Intro_Maven_Gradle_Comparison.adoc @@ -0,0 +1,57 @@ + + +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. + +xref:Case_Study_Mill_vs_Maven.adoc[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. Small mill + projects require minimal effort to get started, and larger Mill projects have a consistent + structure building on these defaults. + +* **Mill makes customizing the build tool much easier than Maven**. Projects usually + grow beyond just compiling a single language: needing custom + code generation, linting workflows, output artifacts, or support for + additional 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**: Not just the + built-in tasks that Mill ships with, but also any custom tasks or modules. + This maximizes performance and snappiness of + your command-line build workflows, and especially matters in larger codebases where builds + tend to get slow: a Maven `clean install` taking over a minute might take just a + few seconds in Mill. + +xref:Case_Study_Mill_vs_Gradle.adoc[Compared to Gradle]: + +* **Mill follows Gradle's conciseness**: Rather than pages and pages of verbose XML, every + line 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. + Skimming and understanding a 100-line Mill `build.mill` file is + often much easier than skimming the equivalent 500-line Maven `pom.xml`. + +* **Mill builds more performant**: Although both Mill and Gradle automatically cache and + parallelize your build, Mill does so with much less fixed overhead, resulting in 2-3x + speedups in common command-line workflows. This means less time waiting for your build + tool, and more time focusing on the things that really matter to your project. + +* **Mill enforces best practices by default**. All Mill tasks are cached by default, even + custom tasks. All Mill tasks write their output to disk xref:Out_Dir.adoc[a + standard place]. All task inter-dependencies are automatically captured, without + needing manual annotation. All Mill builds are incremental, not just tasks but also + xref:The_Mill_Evaluation_Model.adoc#_caching_at_each_layer_of_the_evaluation_model[configuration + and other phases]. Where Gradle requires considerable + https://docs.gradle.org/current/userguide/incremental_build.html[effort and expertise] + to maintain your build, Mill automates it so the + easiest thing to do is almost always the right thing to do. + +Mill build files are written in Scala, but you do not need to have prior experience +in Scala to read or write them. Like Gradle Groovy or Maven XML, it's easy to learn +enough Scala for Mill without needing to become an expert in the language. + diff --git a/example/package.mill b/example/package.mill index f5972185613..7c899d6063e 100644 --- a/example/package.mill +++ b/example/package.mill @@ -89,6 +89,16 @@ object `package` extends RootModule with Module { val upstreamOpt = upstreamCross(this.millModuleSegments.parts.dropRight(1).last) .flatMap(_.valuesToModules.get(List(crossValue))) + def testRepoRoot = T{ + os.copy(super.testRepoRoot().path, T.dest, mergeFolders = true) + for(suffix <- Seq("build.sc", "build.mill", "build.mill.scala")){ + for (lines <- buildScLines() if os.exists(T.dest / suffix)) { + os.write.over(T.dest / suffix, lines.mkString("\n")) + } + } + PathRef(T.dest) + } + def resources = upstreamOpt match { case None => T{ Seq(super.testRepoRoot()) } case Some(upstream) => T{ diff --git a/example/scalalib/basic/4-builtin-commands/build.mill b/example/scalalib/basic/4-builtin-commands/build.mill index ea04df9f80c..9d0926bc69b 100644 --- a/example/scalalib/basic/4-builtin-commands/build.mill +++ b/example/scalalib/basic/4-builtin-commands/build.mill @@ -1,3 +1,12 @@ +// Mill comes with a number of useful commands out of the box. These are listed +// in the API Docs: +// +// * {mill-doc-url}/api/latest/mill/main/MainModule.html[mill.main.MainModule] +// +// Mill's built-in commands are typically not directly related to building your +// application code, but instead are utilities that help you understand and work +// with your Mill build. +// // == Example `build.mill` // // The following examples will be assuming the `build.mill` file given below: