diff --git a/build.sc b/build.sc index cfabf1f3cbc..c14ecac4a28 100644 --- a/build.sc +++ b/build.sc @@ -1755,7 +1755,7 @@ object docs extends Module { s"""site: | title: Mill | url: ${if (authorMode) s"${T.dest}/site" else Settings.docUrl} - | start_page: mill::Intro_to_Mill_for_Scala.adoc + | start_page: mill::Java_Intro_to_Mill.adoc | keys: | google_analytics: 'G-1C582ZJR85' | diff --git a/docs/modules/ROOT/images/IntellijApp.png b/docs/modules/ROOT/images/IntellijApp.png new file mode 100644 index 00000000000..6cec5f7a17c Binary files /dev/null and b/docs/modules/ROOT/images/IntellijApp.png differ diff --git a/docs/modules/ROOT/images/IntellijBuild.png b/docs/modules/ROOT/images/IntellijBuild.png new file mode 100644 index 00000000000..5b4f4a1a06f Binary files /dev/null and b/docs/modules/ROOT/images/IntellijBuild.png differ diff --git a/docs/modules/ROOT/images/IntellijRefresh.png b/docs/modules/ROOT/images/IntellijRefresh.png new file mode 100644 index 00000000000..c9c8d852ff3 Binary files /dev/null and b/docs/modules/ROOT/images/IntellijRefresh.png differ diff --git a/docs/modules/ROOT/images/VSCodeApp.png b/docs/modules/ROOT/images/VSCodeApp.png new file mode 100644 index 00000000000..3cd63e30e55 Binary files /dev/null and b/docs/modules/ROOT/images/VSCodeApp.png differ diff --git a/docs/modules/ROOT/images/VSCodeBuild.png b/docs/modules/ROOT/images/VSCodeBuild.png new file mode 100644 index 00000000000..99fde7b89fe Binary files /dev/null and b/docs/modules/ROOT/images/VSCodeBuild.png differ diff --git a/docs/modules/ROOT/images/VSCodeRefresh.png b/docs/modules/ROOT/images/VSCodeRefresh.png new file mode 100644 index 00000000000..bdbb2ceab8e Binary files /dev/null and b/docs/modules/ROOT/images/VSCodeRefresh.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index c5062427a8e..9cd699435c8 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,13 +2,6 @@ // do this other thing, etc. We touch on a lot of topics about how Mill works, // 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:Scala_Intro_to_Mill.adoc[] -* xref:Scala_Installation_IDE_Support.adoc[] -* xref:Scala_Builtin_Commands.adoc[] -* xref:Scala_Build_Examples.adoc[] -* xref:Scala_Module_Config.adoc[] -* xref:Scala_Web_Build_Examples.adoc[] .Java Quick Start * xref:Java_Intro_to_Mill.adoc[] @@ -18,6 +11,14 @@ * xref:Java_Module_Config.adoc[] * xref:Java_Web_Build_Examples.adoc[] +.Scala Quick Start +* xref:Scala_Intro_to_Mill.adoc[] +* xref:Scala_Installation_IDE_Support.adoc[] +* xref:Scala_Builtin_Commands.adoc[] +* xref:Scala_Build_Examples.adoc[] +* xref:Scala_Module_Config.adoc[] +* xref:Scala_Web_Build_Examples.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/Scala_Build_Examples.adoc b/docs/modules/ROOT/pages/Scala_Build_Examples.adoc index 5f48ac20dce..4cd74af848f 100644 --- a/docs/modules/ROOT/pages/Scala_Build_Examples.adoc +++ b/docs/modules/ROOT/pages/Scala_Build_Examples.adoc @@ -75,7 +75,7 @@ include::example/thirdparty/fansi.adoc[] https://github.com/com-lihaoyi/Ammonite[Ammonite] is an ergonomic Scala REPL. -=== Scala-ClI +=== Scala-CLI https://github.com/VirtusLab/scala-cli[Scala-CLI] is the primary CLI tool that runs when you enter `scala` in the terminal. It is able to compile, test, run, diff --git a/docs/modules/ROOT/partials/Installation_IDE_Support.adoc b/docs/modules/ROOT/partials/Installation_IDE_Support.adoc index 2e3e30221f0..66ff6004bcb 100644 --- a/docs/modules/ROOT/partials/Installation_IDE_Support.adoc +++ b/docs/modules/ROOT/partials/Installation_IDE_Support.adoc @@ -1,60 +1,186 @@ +++++ + + +++++ + +For all the examples in this documentation, there is a `download` link that provides +a zip file containing the full example ready to use. These examples come with a `./mill` +script you can use to immediately begin working with the project, needing only a JVM installed +globally The best method of installing Mill is to just install a <<_bootstrap_scripts,bootstrap script>>. This script can determine the best version to be used by a project (e.g. by reading a `.mill-version` or `.config/mill-version` file or a `MILL_VERSION` environment variable) and will use this exact Mill version. If the determined Mill version is not installed locally, it will be downloaded automatically. -[#_bootstrap_scripts] -== Bootstrap Scripts +== IDE Support -There are currently two bootstrap script available: +:link-metals: https://scalameta.org/metals/ -* the rather simple `mill` script <<_mills_bootstrap_script_linuxos_x_only,in the root of th Mill repository>>, which only works on Linux and Unix-like machines, or -* <<_millw,the `lefou/millw` script>>, an external project with more features and more supported platforms. +Mill supports IntelliJ and VSCode, both via the standard +https://build-server-protocol.github.io/[Build Server Protocol] -Using `millw` is recommended. -We plan to merge both script in the future. +=== IntelliJ -In general, bootstrap scripts are the recommended way of installing Mill, -because they reduce the chance of errors due to the installed version of Mill -being incompatible with the version expected by your build. +To use Mill with IntelliJ, first ensure you have the free +https://plugins.jetbrains.com/plugin/1347-scala[IntelliJ Scala Plugin] +installed. This is necessary as Mill build files are written in Scala, +even if you are using it to build a Java project. -All bootstrap scripts can be installed globally and/or per project. +Once you have the plugin installed, you can use IntelliJ to open any project +containing a Mill `build.sc` file, and IntelliJ will automatically load the +Mill build. This will provide support both for your application code, +as well as the code in the `build.sc`: -=== Global installation +image::IntellijApp.png[] -After installing the script in a global or user-wide location, you can use it everywhere. -If it detects project-specific configuration of the Mill version, it will download and use this exact version. +image::IntellijBuild.png[] -=== Project-specific installation +If you make changes to your Mill `build.sc`, you can ask Intellij to load +those updates by opening the "BSP" tab and clicking the "Refresh" button -You can also add the script to your project as `mill`. -This makes it easier for new contributors to build your project, as they don't have to install Mill before they can start. -Anyone who wants to work with the project can simply use the `./mill` script directly. +image::IntellijRefresh.png[] + +==== IntelliJ IDEA XML Support + +Apart from using the Build Server Protocol, you can also generate IDEA project +files directly with Mill. This is probably the preferred way if you work on +polyglot projects and need support for other languages like Kotlin or AspectJ, +which are currently not specifically configured over BSP. + +To generate IntelliJ IDEA project files into `.idea/`, run: [source,bash] ---- -./mill --version -./mill __.compile # double underscore +./mill mill.idea.GenIdea/idea ---- -In-project bootstrap scripts are also useful for running Mill in CI/CD, ensuring -that your build server like Jenkins or Github Actions has the correct version of Mill present to build, compile or test your code. +This will generate the XML files IntelliJ uses to configure your project + +``` +.idea +.idea/scala_settings.xml +.idea/mill_modules +.idea/mill_modules/.iml +.idea/mill_modules/mill-build.iml +.idea/mill_modules/test.iml +.idea/libraries +.idea/libraries/mill_scalalib_2_13_0_11_10_jar.xml +... +.idea/workspace.xml +.idea/modules.xml +.idea/scala_compiler.xml +.idea/misc.xml +``` + +After the files are generated, you can open the folder in IntelliJ to load the project +into your IDE. If you make changes to your Mill `build.sc`, you can update the project config +those updates by running `./mill mill.idea.GenIdea/idea` again. + +=== VSCode + +To use Mill with VSCode, first ensure you have the free +https://marketplace.visualstudio.com/items?itemName=scalameta.metals[Metals VSCode Scala language server] +installed. This is necessary as Mill build files are written in Scala, +even if you are using it to build a Java project. + +Once you have the language server installed, you can ask VSCode to open any folder +containing a Mill `build.sc` file, and VSCode will ask you to import your +Mill build. This will provide support both for your application code, +as well as the code in the `build.sc`: + +image::VSCodeApp.png[] + +image::VSCodeBuild.png[] + +If you make changes to your Mill `build.sc`, you can ask VSCode to load +those updates by opening the "BSP" tab and clicking the "Refresh" button + +image::VSCodeRefresh.png[] + +=== Debugging IDE issues + +In case things go wrong, it can be sometimes hard to find the cause. +BSP is just a protocol, and as such, issues on the server side (the Mill BSP +server) might not well propagated to the BSP client (your IDE). + +For that reason Mill BSP server is writing a log file under +`.bsp/mill-bsp.stderr`, where you can find various information about what's +going on. Its content should look familiar, as it contains regular Mill +output accompanied by additional BSP client-server communication details. + +You can increase the verbosity of that log file, when you run Mill with +`--debug` at installation time (of the BSP discovery file). + +[source,bash] +---- +mill --debug mill.bsp.BSP/install +---- + +=== BSP Gotchas: Mismatching JVM versions + +A common issue for poor performance can be a mismatch of the JVMs. +In such a case the Mill BSP server started by a BSP client like Metals is using a _different_ JVM than `mill` is using when started from the command line. +In such a scenario, every Mill invocation using the other JVM will inadvertently invalidate Mills target caches. +This effectively leads to full reevaluation of all invoked Mill targets and appears as "bad performance". + +To detect if this is the case, + +1. import the project in the BSP client. +2. Wait until the BSP import process has finished. +3. Then run `mill __.compile` in the terminal. +4. Now watch the IDE, to see if the compile command invoked in the terminal has triggered compilation on the build server. + +If this happens, you're using different JVMs. +Unfortunately, this is rather difficult to "defend" programmatically in Mill itself. +It is an explicit design goal of Mill, that it should work in different environments. +It is evident and likely unintentional that you have two conflicting local environments. + +To fix this it's required to find where this difference stems from. +As a starting point, -[#_mills_bootstrap_script_linuxos_x_only] -=== Mill's in-repo Bootstrap Script (Linux/OS-X Only) +* Find out which JVM is used for Mill on the CLi. `mill --version` reports its JVM. -You can find this script in the root of the Mill repository, or on each release page. -To get the latest version run the following command: +* Search the `.bsp/mill-bsp.stderr` file for a line starting with `"Updating Evaluator"`. +It should contain all env variables (particularly `JAVA_HOME`) used by the BSP server. + +Once you found and fixed that and the environments are the same, `clean` and restarting BSP should work as expected. + +[#_bootstrap_scripts] +== Bootstrap Scripts + +Although the Mill example projects come with their own `./mill` bootstrap script, +you can also download it manually: [source,bash,subs="verbatim,attributes"] ---- curl -L {mill-github-url}/releases/download/{mill-last-tag}/{mill-last-tag} > mill && chmod +x mill +echo {mill-last-tag} > .mill-version ---- -The `mill` command will automatically use the version specified by the -bootstrap script, even if you installed it via other means. -The `./mill` file has a version number embedded within it, which you can update simply by editing the script. +Downloading a `mill` bootstrap script to the root of your project repository helps make it easier for +new contributors to build your project, as they don't have to install Mill before they can start. +Anyone who wants to work with the project can simply use the `./mill` script directly. + +[source,bash] +---- +./mill --version +./mill __.compile # double underscore +---- + +In general, bootstrap scripts are the recommended way of installing Mill. +Similar to `./gradlew` or `./mvnw`, the `./mill` bootstrap script +reduces the chance of errors due to the installed version of Mill +being incompatible with the version expected by your build. +In-project bootstrap scripts are also useful for running Mill in CI/CD, ensuring +that your build server like Jenkins or Github Actions has the correct version of Mill +present to build, compile or test your code. === `millw` @@ -79,6 +205,32 @@ You can also install it on Homebrew via https://github.com/lefou/homebrew-millw[ brew install lefou/millw/millw ---- + +== Updating Mill + +Typically, most Mill projects use a `.mill-version` file to configure what version +to use. You can update the version specified in this file in order to change the version +of Mill. The file path `.config/mill-version` is also supported. If neither is provided, +the `./mill` bootstrap script will use the `DEFAULT_MILL_VERSION` it has built in. + +To choose a different Mill version on an ad-hoc basis, e.g. for experimentation, you can pass +in a `MILL_VERSION` environment variable, e.g. + +[source,bash] +---- +MILL_VERSION=0.5.0-3-4faefb mill __.compile +---- + +or + +[source,bash] +---- +MILL_VERSION=0.5.0-3-4faefb ./mill __.compile +---- + +to override the Mill version manually. This takes precedence over the version +specified in `./mill`, `.config/mill-version` or `.mill-version` + == Other installation methods Of course, you can also use the package manager of your operating system or distribution. @@ -194,181 +346,6 @@ asdf install mill latest asdf global mill latest --- -== IDE Support -:link-metals: https://scalameta.org/metals/ - -To support various IDEs and Language Servers, Mill supports the -https://build-server-protocol.github.io/[Build Server Protocol] in version -{bsp-version} and has a <>. - -In addition to BSP, Mill also supports -<> -directly. - - -=== Build Server Protocol (BSP) - -The Build Server Protocol has the concept of BSP server discovery, which means: -A BSP client can connect to any BSP server, as long as there is a connection -file under the `.bsp/` directory. - -To install a BSP connection file `.bsp/mill-bsp.json` for Mill, run: - -[source,bash] ----- -mill mill.bsp.BSP/install ----- - -Working known clients of the BSP server are IntelliJ IDEA and {link-metals}[Metals]. - -You can fine control some BSP server options by specifying command options: - -|=== -| Option | Description -|`--jobs` `n` | Use `n` threads in parallel to run tasks. A value of `0` means -to use as many threads as the system has cpu cores. -|=== - - -[source] - -[NOTE] --- -*Using Metals* - -When using Metals by default Bloop will be used as your build server unless -you explicitly choose Mill. When in a Mill workspace use the "Switch Build -Server" command from Metals which will allow you to switch to using Mill as -your build server. If no `.bsp/mill-bsp.json` file exists, Metals will -automatically create it for you and then connect to Mill. --- - -[CAUTION] --- -*Updating older setups* - -In the past, we provided SemanticDB support via `mill.scalalib.bsp.ScalaMetalsSupport` -trait, which had to be mixed-in to your Scala modules. This is no longer needed and -deprecated. You should remove these mix-ins. -`ScalaMetalsSupport` trait is now deprecated and will be removed in the future. --- - -=== If things go wrong - -In case things go wrong, it can be sometimes hard to find the cause. -BSP is just a protocol, and as such, issues on the server side (the Mill BSP -server) might not well propagated to the BSP client (your IDE). - -For that reason Mill BSP server is writing a log file under -`.bsp/mill-bsp.stderr`, where you can find various information about what's -going on. Its content should look familiar, as it contains regular Mill -output accompanied by additional BSP client-server communication details. - -You can increase the verbosity of that log file, when you run Mill with -`--debug` at installation time (of the BSP discovery file). - -[source,bash] ----- -mill --debug mill.bsp.BSP/install ----- - -=== BSP Gotchas: Mismatching JVM versions - -A common issue for poor performance can be a mismatch of the JVMs. -In such a case the Mill BSP server started by a BSP client like Metals is using a _different_ JVM than `mill` is using when started from the command line. -In such a scenario, every Mill invocation using the other JVM will inadvertently invalidate Mills target caches. -This effectively leads to full reevaluation of all invoked Mill targets and appears as "bad performance". - -To detect if this is the case, - -1. import the project in the BSP client. -2. Wait until the BSP import process has finished. -3. Then run `mill __.compile` in the terminal. -4. Now watch the IDE, to see if the compile command invoked in the terminal has triggered compilation on the build server. - -If this happens, you're using different JVMs. -Unfortunately, this is rather difficult to "defend" programmatically in Mill itself. -It is an explicit design goal of Mill, that it should work in different environments. -It is evident and likely unintentional that you have two conflicting local environments. - -To fix this it's required to find where this difference stems from. -As a starting point, - -* Find out which JVM is used for Mill on the CLi. `mill --version` reports its JVM. - -* Search the `.bsp/mill-bsp.stderr` file for a line starting with `"Updating Evaluator"`. -It should contain all env variables (particularly `JAVA_HOME`) used by the BSP server. - -Once you found and fixed that and the environments are the same, `clean` and restarting BSP should work as expected. - - -=== Using Bloop (standalone BSP server) - -If you wish to use Bloop as your build server (it is the default metals BSP -implementation) with metals / vscode, consider using the mill bloop plugin. - -xref:contrib/bloop.adoc[Bloop Plugin] - -This is preferred to the instructions (currently) on the bloop website. - -Please be aware, that the Bloop contrib plugin is maintained by the community -and is probably not on a par with the built-in BSP server. - - -=== IntelliJ IDEA Support - -IntelliJ IDEA also supports the BSP protocol. To use this support, just follow -the directions in <<_build_server_protocol_bsp>>. - -Additionally, you can generate IDEA project files directly with Mill. -This is probably the preferred way if you work on polyglot projects and need -support for other languages like Kotlin or AspectJ, which are currently not -specifically configured over BSP. - -To generate IntelliJ IDEA project files into `.idea/`, run: - -[source,bash] ----- -mill mill.idea.GenIdea/idea ----- - -== Updating Mill - -If you have installed Mill via the recommended <<_bootstrap_scripts,`Bootstrap Script`>> -method, you don't need to install multiple version of Mill explicitly. - -Follow the next <<_overriding_mill_versions>> section for details. - -== Overriding Mill Versions - - -Apart from downloading and installing new versions of Mill globally, there are -a few ways of selecting/updating your Mill version. This will only work, if you -have choosen one of the <<_bootstrap_scripts,Boostrap script methods>>: - -* Create a `.mill-version` or `.config/mill-version` file to specify the version of Mill you wish to use: -[source,bash] ----- -echo "0.5.0" > .mill-version ----- - -`.mill-version` takes precedence over `.config/mill-version` or the version of Mill specified in the `./mill` script. - -* Pass in a `MILL_VERSION` environment variable, e.g. -[source,bash] ----- -MILL_VERSION=0.5.0-3-4faefb mill __.compile ----- - -or - -[source,bash] ----- -MILL_VERSION=0.5.0-3-4faefb ./mill __.compile ----- - -to override the Mill version manually. This takes precedence over the version -specified in `./mill`, `.config/mill-version` or `.mill-version` === Automatic Mill updates diff --git a/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc b/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc index 932cfbbe1fd..b002f652d6f 100644 --- a/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc +++ b/docs/modules/ROOT/partials/Intro_to_Mill_Header.adoc @@ -1,19 +1,23 @@ -{mill-github-url}[Mill] is a JVM build tool that supports {language}. Mill aims for performance, -maintainability, and flexibility: +{mill-github-url}[Mill] is a JVM build tool that supports {language}. Mill aims to make +your JVM project's build process performant, maintainable, and flexible: -* *Performance*: Mill's xref:Tasks.adoc[build graph] automatically caches and xref:#_parallel_task_execution[parallelizes] build +* *Performance*: Mill's xref:Tasks.adoc[build graph] automatically + xref:The_Mill_Evaluation_Model.adoc#_caching_at_each_layer_of_the_evaluation_model[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. * *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]), + (via xref:{language}_Installation_IDE_Support.adoc#_intellij[IntelliJ] or + xref:{language}_Installation_IDE_Support.adoc#_vscode[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. -* *Flexibility*: Mill lets you write <>, rather than +* *Flexibility*: Mill lets you write your xref:_custom_build_logic[custom build logic] + in type-checked code, 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 diff --git a/example/javabuilds/2-custom-tasks/build.sc b/example/javabuilds/2-custom-tasks/build.sc index d51e9be4a18..68414d37bd6 100644 --- a/example/javabuilds/2-custom-tasks/build.sc +++ b/example/javabuilds/2-custom-tasks/build.sc @@ -12,13 +12,14 @@ object foo extends RootModule with JavaModule { val version = ivyDep.dep.version s""" "$org:$name:$version" """ } + val ivyDepsString = prettyIvyDeps.mkString(" + \"\\n\" + \n") os.write( T.dest / s"MyDeps.java", s""" |package foo; |public class MyDeps { | public static String value = - | ${prettyIvyDeps.mkString(" + \"\\n\" + \n")}; + | $ivyDepsString; |} """.stripMargin )