Merge branch 'main' into tr-run-exclusive

Author: lefou

changelog.adoc

@@ -489,7 +489,7 @@ _2025-05-10_
 
 * fix: Use root qualifier in Discover macro ({link-pr}/5055[#5055])
 * Fix selective execution when multiple changes are made to one module under `--watch` ({link-pr}/5032[#5032])
-* Add ability to define `package` `ExternalModule`s that can be calle via just `pkg.path/` rather than `pkg.path.ObjectName/` ({link-pr}/4920[#4920])
+* Add ability to define `package` ``ExternalModule``s that can be calle via just `pkg.path/` rather than `pkg.path.ObjectName/` ({link-pr}/4920[#4920])
 * Backport `javascriptlib` and `pythonlib` improvements from `main` branch ({link-pr}/4893[#4893])
 * Fix wildcard and type selector query bugs ({link-pr}/4862[#4862])
 * Lots of Mill `main` branch compatibility changes, adding the new name and deprecating the old one
@@ -1418,7 +1418,7 @@ __New features__
 __Fixes and Improvements__
 
 * Better detect Windows Subsystem for Linux environments {link-pr}/2901[#2901]
-* Avoid evaluating `Task.Input`s twice {link-pr}/2952[#2952]
+* Avoid evaluating ``Task.Input``s twice {link-pr}/2952[#2952]
 * Deduplicate (anonymous) tasks in results {link-pr}/2959[#2959]
 * Synchronize `evaluateGroupCached` to avoid concurrent access to cache  {link-pr}/2980[#2980]
 * Properly sanitize Windows reserved names and symbols in evaluator paths {link-pr}/2964[#2964], {link-pr}/2965[#2965]
@@ -2450,7 +2450,7 @@ The API is suspected to change before a 0.10.0 releae.*
 
 _Changes since {prev-version}:_
 
-* `ScalaModule with PublishModule`: the `scala-library` artifact is now always part of the dependencies in published `pom.xml`s and `ivy.xml`s
+* `ScalaModule with PublishModule`: the `scala-library` artifact is now always part of the dependencies in published ``pom.xml``s and `ivy.xml`s
 * New `JavaModule.mandatoryMvnDeps` target to provide essential dependencies like scala-library without forcing the user to call `super.mvnDeps`
 * `ScalaJSModule.scalaLibraryMvnDeps` no longer contains the scala-js-library, but only the scala-library; if you need that, use `ScalaJSModule.mandatoryMvnDeps` instead.
 * `import $ivy` support `$MILL_BIN_PLATFORM` variable and a new sort notations for external plugins
@@ -3280,7 +3280,7 @@ _2018-03-04_
 
 * Speed up Mill client initialization by another 50-100ms
 
-* Speed up incremental `assembly`s in the common case where upstream dependencies do not change.
+* Speed up incremental ``assembly``s in the common case where upstream dependencies do not change.
 
 * Make `ScalaJSModule#run` work with main-method discovery
 

dist/package.mill

@@ -223,30 +223,35 @@ object `package` extends MillJavaModule with DistModule {
     prepareBootstrapLauncher(millBootstrapBat().path, Task.dest, build.millVersion(), "mill.bat")
   }
 
-  def examplePathsWithArtifactName0: Task[Seq[PathRef]] = Task.Input {
-    for (exampleMod <- build.example.exampleModules) yield PathRef(exampleMod.moduleDir)
+  def examplePaths: Task[Seq[os.Path]] = Task.Input {
+    build.example.exampleModules.map(_.moduleDir)
   }
 
-  def examplePathsWithArtifactName = Task {
-    for (pr <- examplePathsWithArtifactName0()) yield {
-      val example = pr.path.subRelativeTo(BuildCtx.workspaceRoot)
+  def examplePathRefs: Task[Seq[PathRef]] = Task.Sources(
+    build.example.exampleModules.map(_.moduleDir)*
+  )
+
+  def exampleArtifactNames = Task {
+    for (path <- examplePaths()) yield {
+      val example = path.subRelativeTo(BuildCtx.workspaceRoot)
       val artifactName = example.segments.mkString("-")
-      (pr, s"${build.dist.artifactFileNamePrefix()}-$artifactName")
+      (path, s"${build.dist.artifactFileNamePrefix()}-$artifactName")
     }
   }
 
   def exampleZips: T[Seq[PathRef]] = Task {
-    examplePathsWithArtifactName().map { case (examplePath, exampleStr) =>
-      os.copy(examplePath.path, Task.dest / exampleStr, createFolders = true)
-      val ignoreErrorsOnCI = Task.dest / exampleStr / "ignoreErrorsOnCI"
-      if (os.exists(ignoreErrorsOnCI)) os.remove(ignoreErrorsOnCI)
-      val buildMill = Task.dest / exampleStr / "build.mill"
-      os.write.over(buildMill, s"//| mill-version: ${build.millVersion()}\n" + os.read(buildMill))
-      os.copy(bootstrapLauncher().path, Task.dest / exampleStr / "mill")
-      os.copy(bootstrapLauncherBat().path, Task.dest / exampleStr / "mill.bat")
-      val zip = Task.dest / s"$exampleStr.zip"
-      os.proc("zip", "-r", zip, exampleStr).call(cwd = Task.dest)
-      PathRef(zip)
+    examplePathRefs().zip(exampleArtifactNames()).map {
+      case (pr, (examplePath, exampleStr)) =>
+        os.copy(pr.path, Task.dest / exampleStr, createFolders = true)
+        val ignoreErrorsOnCI = Task.dest / exampleStr / "ignoreErrorsOnCI"
+        if (os.exists(ignoreErrorsOnCI)) os.remove(ignoreErrorsOnCI)
+        val buildMill = Task.dest / exampleStr / "build.mill"
+        os.write.over(buildMill, s"//| mill-version: ${build.millVersion()}\n" + os.read(buildMill))
+        os.copy(bootstrapLauncher().path, Task.dest / exampleStr / "mill")
+        os.copy(bootstrapLauncherBat().path, Task.dest / exampleStr / "mill.bat")
+        val zip = Task.dest / s"$exampleStr.zip"
+        os.proc("zip", "-r", zip, exampleStr).call(cwd = Task.dest)
+        PathRef(zip)
     }
   }
 

example/depth/sandbox/1-task/build.mill

@@ -1,10 +1,3 @@
-// In order to help manage your build, Mill performs some rudimentary filesystem
-// sandboxing to keep different tasks and modules from interfering with each other.
-// This tries to ensure your tasks only read and write from their designated `.dest/`
-// folders, which are unique to each task and thus guaranteed not to collide with
-// the filesystem operations of other tasks that may be occurring in parallel.
-//
-//
 // === `Task.dest`
 // The standard way of working with a task's `.dest/` folder is through the `Task.dest`
 // property. This is available within any task, and gives you access to the
@@ -24,11 +17,14 @@ object foo extends Module {
 .../out/foo/tDestTask.dest
 */
 
+// If you really need to reference paths outside of the `Task.dest`, you can do
+// so via `BuildCtx.workspaceRoot`.
+
 // === Filesystem Read/Write Checks
 //
 // Mill enforces limits on what you can read and write while a task is executing.
 // In general, a task may only write to its own `Task.dest` folder, and may only
-// read from the `PathRef`s provided to it from upstream tasks
+// read from the ``PathRef``s provided to it from upstream tasks
 
 def bannedWriteTask = Task {
   os.write(BuildCtx.workspaceRoot / "banned-path", "hello")
@@ -63,9 +59,9 @@ error: ...Reading from out/foo/tDestTask.json not allowed during execution of `b
 
 val listed = BuildCtx.watchValue(os.list(BuildCtx.workspaceRoot).map(_.last))
 
-// === Disabling Task Sandboxing
+// === Bypassing Task Sandboxing
 //
-// You can disable Mill's filesystem read/write limitations via
+// You can bypass Mill's filesystem read/write limitations via
 // `BuildCtx.withFilesystemCheckerDisabled`. Note that this bypasses the
 // best-practices that Mill tries to enforce on your tasks and may result in strange
 // bugs around caching, parallelism, and invalidation, so you shouldn't do this unless

example/depth/sandbox/2-test/build.mill

@@ -63,7 +63,7 @@ object bar extends MyModule
 // one another, which helps keep tests stable and deterministic even when run in
 // parallel
 //
-// === Escaping the Test Sandbox
+// === Bypassing the Test Sandbox
 
 // Within a test, you can use the `MILL_WORKSPACE_ROOT` environment variable
 // to access the workspace root directory:
@@ -89,9 +89,7 @@ object qux extends JavaModule {
 */
 
 //
-// === Disabling Test Sandboxing
-//
-// Test sandboxing can be disabled by setting `def testSandboxWorkingDir = false`
+// Test sandboxing can also be disabled by setting `def testSandboxWorkingDir = false`
 // on your test module, which makes your unit tests run in the root of your
 // project workspace, with full access to the project files on disk.
 //

example/extending/jvmcode/1-subprocess/build.mill

@@ -4,7 +4,7 @@
 //
 // * `defaultResolver().classpath` to resolve the dependencies from Maven Central,
 //   converting `org:name:version` coordinates (and their transitive dependencies) to
-//   `PathRef`s referring to files on disk
+//   ``PathRef``s referring to files on disk
 //
 // * `Jvm.runSubprocess`, which runs the given classpath files in a subprocess, starting
 //   from specified `mainClass`

example/javalib/linting/6-pmd/build.mill

@@ -0,0 +1,76 @@
+// `PmdModule` Performs checks on Java source files using https://pmd.github.io/[PMD] and generates reports from these checks.
+//
+// PMD is a source code analyzer for Java that finds common programming flaws like unused variables,
+// empty catch blocks, unnecessary object creation, and more.
+//
+// To customize this plugin in a Java module:
+//
+// 1. Extend JavaModule with PmdModule.
+// 2. Define a PMD ruleset file(s) with `pmdRulesets` (default is `pmd-rules.xml` in root).
+// 3. Define the PMD version with `pmdVersion`.
+
+package build
+
+import mill._, javalib._
+import mill.javalib.pmd.PmdModule
+
+object `package` extends JavaModule, PmdModule {
+  def pmdVersion = "7.15.0"
+}
+
+// Here's an example of a simple PMD ruleset file and a single Java source file.
+
+/** See Also: pmd-ruleset.xml */
+/** See Also: src/foo/EmptyCatchBlock.java */
+
+// CAUTION: Be careful, rule formats can differ between major PMD versions.
+
+// You can either run the `pmd` command on selected modules
+// or use the external module `mill.javalib.pmd/`.
+
+/** Usage
+
+> ./mill pmd -s true -v false # <1>
+Running PMD ...
+Writing PMD output to .../out/pmd.dest/pmd-output.text ...
+...src/foo/EmptyCatchBlock.java:7:	EmptyCatchBlock:	Avoid empty catch blocks...
+PMD found 1 violation(s)
+
+> ./mill mill.javalib.pmd/ # <2>
+error: Running PMD ...
+error: Writing PMD output to .../out/mill/javalib/pmd/PmdModule/pmd.dest/pmd-output.text ...
+error: 1 tasks failed
+error: mill.javalib.pmd.PmdModule.pmd PMD found 1 violation(s)
+
+*/
+// <1> `-s` shows the results on the console, `-v` does not fail the build
+// <2> Use the external `mill.javalib.pmd` module with default configuration
+//
+// The `pmd` command accepts several options to customize its behavior. Mill supports:
+//
+// * `--stdout` / `-s` : Enable output to stdout. False by default. (PMD will write output to a file regardless of this option).
+//
+// * `--format` / `-f` : Output format of the report (`text`, `xml`, `html`). Defaults to `text`.
+//
+// * `--fail-on-violation` / `-v` : Fail if violations are found (true by default).
+//
+// For a full list of PMD options, see the PMD documentation:
+// https://pmd.github.io/pmd/pmd_userdocs_cli_reference.html.
+//
+// Here's an example of producing HTML report:
+
+/** Usage
+> ./mill pmd -f "html" -s true -v false
+Writing PMD output to .../out/pmd.dest/pmd-output.html ...
+...<html><head><title>PMD</title></head><body>...
+...<center><h3>PMD report</h3></center><center><h3>Problems found</h3></center><table align="center" cellspacing="0" cellpadding="3"><tr>...
+...<th>#</th><th>File</th><th>Line</th><th>Problem</th></tr>...
+...<tr bgcolor="lightgrey">...
+...<td align="center">1</td>...
+...<td width="*%">...src/foo/EmptyCatchBlock.java</td>...
+...<td align="center" width="5%">7</td>...
+...<td width="*"><a href="https://docs.pmd-code.org/pmd-doc-7.15.0/pmd_rules_java_errorprone.html#emptycatchblock">Avoid empty catch blocks</a></td>...
+...</tr>...
+...</table></body></html>...
+...PMD found 1 violation(s)...
+*/

example/javalib/linting/6-pmd/pmd-ruleset.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="Example ruleset"
+         xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0
+         https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
+    <description>
+        Example PMD ruleset for Mill integration (Updated for PMD 7.15.0)
+    </description>
+    <rule ref="category/java/errorprone.xml/EmptyCatchBlock"/>
+</ruleset>

example/javalib/linting/6-pmd/src/foo/EmptyCatchBlock.java

@@ -0,0 +1,11 @@
+package foo;
+
+public class EmptyCatchBlock {
+  public void bar() {
+    try {
+      // do something
+    } catch (Exception e) {
+      // violation
+    }
+  }
+}

libs/init/package.mill

@@ -18,10 +18,10 @@ object `package` extends MillPublishScalaModule {
 
   def exampleList: T[PathRef] = Task {
     val data: Seq[(os.SubPath, String)] =
-      build.dist.examplePathsWithArtifactName().map { case (pathRef, str) =>
+      build.dist.examplePaths().zip(build.dist.exampleArtifactNames()).map { case (path, str) =>
         val downloadUrl =
           s"${build.millDownloadUrlCurrent()}/$str.zip"
-        val subPath = pathRef.path.subRelativeTo(BuildCtx.workspaceRoot / "example")
+        val subPath = path.subRelativeTo(BuildCtx.workspaceRoot / "example")
         (subPath, downloadUrl)
       }
 

libs/jvmlib/package.mill

@@ -103,7 +103,8 @@ object `package` extends MillStableScalaModule {
           s"${dep.group}:${dep.id}:${dep.version}"
         },
         "The dependency containing the worker implementation to be loaded at runtime."
-      )
+      ),
+      BuildInfo.Value("pmdVersion", Deps.RuntimeDeps.pmdDist.version)
     )
   }