Support nested build files with relaxed package naming #6504

Emin017 · 2026-01-06T03:44:06Z

This is an attempt to support #5091

Add allNestedBuildFileNames to CodeGenConstants to include both package.* and build.* variants, enabling recognition of both types as nested build files.
Update the code generation and file import logic in CodeGen.scala and FileImportGraph.scala to use allNestedBuildFileNames for identifying nested build files and allowing relaxed package declarations for these files.

Relaxed Package Declarations

This update introduces relaxed package naming for nested mill build files, enabling the same build definition file to be used in different scenarios (as an independent project or as a reusable submodule).

Commit: 0636620

File Type	Allowed Packages	Disallowed Packages	Examples
Root build.mill	Empty package (package build), Exact match	Relaxed match	`package build`, `package build.foo`
Nested build.mill	Empty package (supports independent use), Relaxed match, Exact match	None	`package build`, `package build.foo`, `package build.bar`
Nested package.mill	Relaxed match, Exact match	Empty package	`package build.deps`, `package build.foo.bar`
Other helper files	Relaxed match, Exact match	Empty package	`package build.helpers`

Relaxed Match Definition

A relaxed match occurs when the import path is either:

A package name starting with build* (i.e., package build)
Or if the expected path starts with the package declaration (e.g., package foo, and we can import foo.bar.baz)

val relaxedMatch =
  importSegments.startsWith("build") ||
  expectedImportSegments.startsWith(importSegments + ".")

This means that any package name in the form of package build* is valid, and we can also expect an import path like foo.bar.baz when we have package foo.

Usage Example

We can now import build configuration files from subdirectories:

// build.mill
// Imports FooModule from the deps subdirectory
package build

import mill.*, scalalib.*

trait BarModule extends build.deps.foo.FooModule

// deps/package.mill
package build.deps

// deps/foo/build.mill
package build

import mill.*, scalalib.*

object `package` extends FooModule

// deps/foo/module.mill
package build

import mill.*, scalalib.*

trait FooModule extends ScalaModule { // trait definition in Helper Files
  def scalaVersion = "2.13.16"
}

If the subdirectory imports nested build files, this is also supported:

// build.mill
// Imports FooModule from the deps subdirectory
package build

import mill.*, scalalib.*

trait BarModule extends build.deps.foo.FooModule

// deps/package.mill
package build.deps

// deps/foo/build.mill
package build

import mill.*, scalalib.*

// Foo has its own helper files
import build.project.FooHelper // importing helper this way is now supported

object `package` extends FooModule

// deps/foo/module.mill
package build

import mill.*, scalalib.*

trait FooModule extends ScalaModule { // trait definition in Helper Files
  def scalaVersion = "2.13.16"
}

// deps/foo/project/package.mill
package build.project

// deps/foo/project/version.mill
trait FooHelper {
  // Something here
}

Limitation

This PR does not support importing from nested build.mill. Nested build.mill continues to be usable as an entrypoint when running Mill within that subdirectory, but reuse across directories is achieved by importing helper .mill files.

I believe that if this feature is merged, it will help smooth the migration of several open-source projects (such as Chisel, SpinalHDL, rocket-chip, and Xiangshan) to the new version of Mill, as they currently rely on this functionality in the older version of Mill.

inochisa · 2026-01-08T02:14:31Z

Hi @Emin017, I have seen your PR. Great work. And I have tested on my branch, but got a dependency error:

# ./mill -i dist.run ../misc-ips -i compile

56/69, 1 failed, completed] ============================== compile -explain-cyclic ============================== 2s
build.mill-56] [error] generatedScriptSources Package declaration "package build" in ext/SpinalHDL/package.mill does not match folder structure. Expected: "package build.ext.SpinalHDL"
Package declaration "package build.project" in ext/SpinalHDL/project/Version.mill does not match folder structure. Expected: "package build.ext.SpinalHDL.project"
Package declaration "package build.project" in ext/SpinalHDL/project/package.mill does not match folder structure. Expected: "package build.ext.SpinalHDL.project"
8850/8850, 1 failed, completed] ============================== dist.run xxx/misc-ips -i compile -explain-cyclic ============================== 88s
8850] [error] dist.run dist.run failed with an exception. Result of xxx/mill/out/dist/launcher.dest/run…: 1

My repo is at https://github.com/project-inochi/misc-ips/tree/mill-subproject

In fact, I am also trying to resolve this, but got lots of cycle dependency.

Emin017 · 2026-01-08T02:19:33Z

My repo is at https://github.com/project-inochi/misc-ips/tree/mill-subproject

@inochisa Could you make this repo public? That way, we can see your specific configuration and debug more effectively.

inochisa · 2026-01-08T02:21:47Z

@Emin017 My fault, now it is opened.

Emin017 · 2026-01-08T02:35:58Z

@inochisa I took a look at your repository structure, and I have a general understanding of how the issue is occurring. We may still need to modify the configuration mechanism for searching subfolders and the assertion check mechanism in mill.

Previously, I only considered the following check and usage mechanism:
In the subfolders of our repository, there is only build.mill (without package.mill), and then we can import the traits from the sub-repository configuration into the build.mill in the root repository.

// build.mill
package build

import mill.*, scalalib.*

trait BarModule extends build_.deps.foo.FooModule // extends trait from deps/foo/build.mill

// deps/package.mill
package build.deps

// deps/foo/build.mill
package build

import mill.*, scalalib.*

trait FooModule extends ScalaModule {
  def scalaVersion = "2.13.16"
}

object `package` extends FooModule

However, looking at it now, I realize that I didn't fully consider this aspect. I'll think about making adjustments to this part. (We might also need more relaxed check rules.)

inochisa · 2026-01-08T02:49:54Z

@inochisa I took a look at your repository structure, and I have a general understanding of how the issue is occurring. We may still need to modify the configuration mechanism for searching subfolders and the assertion check mechanism in mill.

Agreed.

Previously, I only considered the following check and usage mechanism: In the subfolders of our repository, there is only build.mill (without package.mill),

I think it is possible to remove this (at least in my repository). I added it as mill always complaint it is not a package.

and then we can import the traits from the sub-repository configuration into the build.mill in the root repository.
// build.mill
package build

import mill.*, scalalib.*

trait BarModule extends build_.deps.foo.FooModule // extends trait from deps/foo/build.mill

I also consider this, but I found it is not nature to do such a thing. Using internal build_ is not documented and confused. In my view, it is more nature to use something like build.deps.foo.FooModule

// deps/package.mill
package build.deps
// deps/foo/build.mill
package build

import mill.*, scalalib.*

trait FooModule extends ScalaModule {
  def scalaVersion = "2.13.16"
}

object `package` extends FooModule
However, looking at it now, I realize that I didn't fully consider this aspect. I'll think about making adjustments to this part. (We might also need more relaxed check rules.)

In this example, the SpinalHDL has its own build lib. This is not resolved in a right way, as mill will generate build_ class for nested build file, which will cause a loop for package import. (This is the next step after this error).

Emin017 · 2026-01-08T13:57:06Z

In this example, the SpinalHDL has its own build lib. This is not resolved in a right way, as mill will generate build_ class for nested build file, which will cause a loop for package import. (This is the next step after this error).

@inochisa I think Mill’s CodeGen will rewrite package name prefixes, which should prevent loops from occurring (at least in this case). Could you explain in more detail when the loop you mentioned for package imports would arise?

Emin017 · 2026-01-08T16:03:27Z

@inochisa I think I roughly understand what you mean. I’ve pushed some new commits, and you can try it based on that. The new support I added includes:

Added detection for the case where build.mill and package.mill coexist in the same directory, since this can lead to duplicate package_ definitions during code generation. However, I’m not entirely sure whether Mill is supposed to support having both build.mill and package.mill present at the same time (I haven't seen this usage in the example yet), this probably needs to be confirmed with @lihaoyi.
By modifying codeGen, I added support for build.mill files in subdirectories to import nested configuration files themselves. For such nested build.mill files, a local build object is generated. This object “shadows” the root-level build alias, allowing local references like import build.foo.Bar to work correctly.

// deps/foo/build.mill
// This is build.mill in subdir, but also import trait from its subdir
package build

import build.foo.Bar
trait fooModule extends Bar

// deps/foo/bar/package.mill
package build.bar

trait Bar {
// Do something here
}

I’m not sure whether there are other aspects I may have overlooked. Please feel free to point them out after testing :)

inochisa · 2026-01-09T01:48:00Z

Thanks for your update @Emin017

Mostly, I think it is works, but I got an weird error for the build. I guess it may not related to this build and it is a new problem? I have found a similar bug here at sbt/sbt#7777. @lihaoyi, could you take a look for it? I have attached the log below.

https://gist.github.com/inochisa/aa362832d7736df7b4d427ac26841a0a

lihaoyi · 2026-01-09T01:50:22Z

@inochisa can you try wrapping everything in an explicit object package extends mill.Module{...}? The last time I hit an error like that wrapping things made it go away, even though I don't really understand why

inochisa · 2026-01-09T02:06:35Z

@lihaoyi Yeah, by adding this, it is resolved, and I got an error related to this PR. It seems like this is related to the package generation.

https://gist.github.com/inochisa/ad1353ea0d2b2a28e72f5ba2fc84fc90

Emin017 · 2026-01-09T02:39:29Z

@lihaoyi Yeah, by adding this, it is resolved, and I got an error related to this PR. It seems like this is related to the package generation.

https://gist.github.com/inochisa/ad1353ea0d2b2a28e72f5ba2fc84fc90

@inochisa Could you sync your latest configuration to the repository? That way, I can reproduce the issue and debug.

inochisa · 2026-01-09T02:55:37Z

@Emin017 I have updated the repository by force push.
And my test command is ./mill -i dist.run <path>/misc-ips -i compile -explain-cyclic

Emin017 · 2026-01-09T04:01:22Z

@inochisa Can you try the latest commit? I think the previous error should have been fixed.

❯ ./mill dist.run misc-ips/ -i compile -explain-cyclic
8850] dist.run
Mill version SNAPSHOT is different than configured for this directory!
Configured version is 1.0.6 (/home/Emin/Workbench/mill/misc-ips/.mill-version)
============================== compile -explain-cyclic ==============================
build.mill-64] compile compiling 10 Scala sources to out/mill-build/compile.dest/classes ...
build.mill-64] [warn] ext/SpinalHDL/project/Version.mill:5:25
build.mill-64] import scala.collection.JavaConverters._
build.mill-64]                         ^^^^^^^^^^^^^^
build.mill-64] object JavaConverters in package scala.collection is deprecated since 2.13.0: Use `scala.jdk.CollectionConverters` instead
build.mill-64] 
build.mill-64] [warn] one warning found
build.mill-64] done compiling
69/69, completed] ========================== compile -explain-cyclic ========================== 8s
[error] Cannot resolve compile. Try `mill resolve _`, `mill resolve __.compile` to see what's available, or `mill __.compile` to run all `compile` tasks
8850/8850, 1 failed, completed] ============================== dist.run misc-ips/ -i compile -explain-cyclic ============================== 9s
8850] [error] dist.run dist.run failed with an exception. Result of /home/Emin/Workbench/mill/out/dist/launcher.dest/run…: 1

inochisa · 2026-01-09T04:21:03Z

@Emin017 Confirmed

# clear && ./mill -i dist.run xxx/misc-ips -i hw.runMain io.inochisa.gen.clock.ClockDetectedVerilog

8850] dist.run
Mill version SNAPSHOT is different than configured for this directory!
Configured version is 1.0.6 (xxx/misc-ips/.mill-version)
build.mill-64] compile compiling 1 Scala source to out/mill-build/compile.dest/classes ...
build.mill-64] done compiling
build.mill-64] compiling 5 Scala sources to out/mill-build/compile.dest/classes ...
build.mill-64] [warn] ext/SpinalHDL/project/Version.mill:5:25
build.mill-64] import scala.collection.JavaConverters._
build.mill-64]                         ^^^^^^^^^^^^^^
build.mill-64] object JavaConverters in package scala.collection is deprecated since 2.13.0: Use `scala.jdk.CollectionConverters` instead
build.mill-64] 
build.mill-64] [warn] one warning found
build.mill-64] done compiling
378] hw.runMain
[Runtime] SpinalHDL dev    git head : 0a2bd7bc67e6ce86c1231386c18cfd8c216919d1
[Runtime] JVM max memory : 30208.0MiB
[Runtime] Current date : 2026.01.09 12:19:05
[Progress] at 0.000 : Elaborate components
[Progress] at 0.016 : PhaseCreateComponent
[Progress] at 0.284 : PhaseDummy
[Progress] at 0.284 : Checks and transforms
[Progress] at 0.284 : PhaseMemBlackBoxingDefault
[Progress] at 0.288 : PhaseDeviceSpecifics
[Progress] at 0.288 : PhaseApplyIoDefault
[Progress] at 0.290 : PhaseNameNodesByReflection
[Progress] at 0.292 : PhaseCollectAndNameEnum
[Progress] at 0.296 : PhaseCheckIoBundle
[Progress] at 0.298 : PhaseCheckHierarchy
[Progress] at 0.301 : PhaseAnalog
[Progress] at 0.303 : PhaseNextifyReg
[Progress] at 0.304 : PhaseRemoveUselessStuff
[Progress] at 0.312 : PhaseRemoveIntermediateUnnameds
[Progress] at 0.316 : PhasePullClockDomains
[Progress] at 0.319 : PhaseInferEnumEncodings
[Progress] at 0.327 : PhaseInferWidth
[Progress] at 0.329 : PhaseNormalizeNodeInputs
[Progress] at 0.333 : PhaseRemoveIntermediateUnnameds
[Progress] at 0.333 : PhaseSimplifyNodes
[Progress] at 0.337 : PhaseCompletSwitchCases
[Progress] at 0.337 : PhaseRemoveUselessStuff
[Progress] at 0.338 : PhaseRemoveIntermediateUnnameds
[Progress] at 0.339 : PhaseCheck_noLatchNoOverride
[Progress] at 0.348 : PhaseCheck_noRegisterAsLatch
[Progress] at 0.349 : PhaseCheckCombinationalLoops
[Progress] at 0.353 : PhaseCheckCrossClock
[Progress] at 0.357 : PhasePropagateNames
[Progress] at 0.368 : PhaseObfuscate
[Progress] at 0.368 : PhaseAllocateNames
[Progress] at 0.374 : PhaseDevice
[Progress] at 0.375 : PhaseGetInfoRTL
[Progress] at 0.376 : PhaseDummy
[Progress] at 0.377 : Generate Verilog to gen
[Progress] at 0.377 : PhaseVerilog
[Done] at 0.417
378/378, completed] ============================== hw.runMain io.inochisa.gen.clock.ClockDetectedVerilog ============================== 19s
8850/8850, completed] ============================== dist.run xxx/misc-ips -i hw.runMain io.inochisa.gen.clock.ClockDetectedVerilog ============================== 25s

inochisa · 2026-01-09T04:24:38Z

@Emin017 I can also confirmed the change for adding Module for every object is not needed anymore.

Emin017 · 2026-01-09T10:38:03Z

CI Status link: runs/20844288189

The relevant tests have passed, and most tests on CI have also passed. The only failure is the "example.androidlib.__.packaged.daemon" test (#6522 which seems unrelated to this change). Therefore, I am marking this PR as ready for review.

EDIT: I have also updated the PR description.

lefou · 2026-01-09T10:49:52Z

@Emin017 I have updated the repository by force push. And my test command is ./mill -i dist.run <path>/misc-ips -i compile -explain-cyclic

The compile task doesn't accept parameters. You need to add -explain-cyclic to your scalacOptions by overriding def scalacOptions.

inochisa · 2026-01-09T10:52:23Z

@Emin017 I have updated the repository by force push. And my test command is ./mill -i dist.run <path>/misc-ips -i compile -explain-cyclic

The compile task doesn't accept parameters. You need to add -explain-cyclic to your scalacOptions by overriding def scalacOptions.

Thanks, it is useless. And I just did a copy paste from the original test, so please ignore this thing.

lihaoyi · 2026-01-10T11:22:05Z

I think this looks great, could you include the example page in the relevant .adoc file and run website.fastPages to make sure the documentation for this feature is readable and makes sense

example/large/multifile/12-import-subdir/build.mill

Signed-off-by: Emin <me@emin.chat>

Signed-off-by: Qiming Chu <cchuqiming@gmail.com>

- Nested build.mill: allow empty package (standalone project) or relaxed match - Nested package.mill: require package declaration, but allow relaxed match - Root build.mill: allow empty or exact match only Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Signed-off-by: Emin <me@emin.chat>

The local `build` object generated inside `object package_` was causing Scala 3 compiler errors ("missing outer accessor") when user code in `abstract class package_` referenced it. This happened because the nested object shadowed the imported `build` alias, breaking outer reference resolution. Solution: Generate the `build` object at package level instead of inside `object package_`. This eliminates the shadowing issue while maintaining the functionality for nested build.mill files to reference sibling modules via `import build.foo.Bar`. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Emin <me@emin.chat>

Signed-off-by: Emin <me@emin.chat>

Emin017 · 2026-01-14T08:48:31Z

@lihaoyi
Hi, I dropped support for importing traits from a nested build.mill, because supporting that seems to require a lot of invasive changes.

The commits I just pushed implement a narrower scope: only importing modules from nested helper .mill files. Implementing just this support wouldn’t require many invasive changes. And even with just this capability, I believe it can still help (or unblock) migrating these open-source projects to the newer Mill version, since it covers the core reuse workflow they depend on.

Also, I’ve updated the PR description accordingly.

Keep legacy `[error] [error] package.mill:...` output, aligned with YamlHeaderPackageTests. Signed-off-by: Emin <me@emin.chat>

lihaoyi · 2026-01-23T01:43:08Z

@Emin017 @inochisa I have put together an alternative implementation over at #6655, please help me review it and try it out

Fixed #5091, a second implementation of #6504

Emin017 · 2026-01-23T07:36:04Z

Superseded by #6655.

Emin017 mentioned this pull request Jan 6, 2026

Absolute paths in package.mill hinder isolated compilation of nested submodules #5091

Closed

Emin017 force-pushed the relax-pkg-naming branch 3 times, most recently from b16122b to d60cd78 Compare January 6, 2026 11:53

Emin017 force-pushed the relax-pkg-naming branch from d60cd78 to 23d984a Compare January 8, 2026 15:58

inochisa mentioned this pull request Jan 9, 2026

Bump mill to version 1.1.0 SpinalHDL/SpinalHDL#1862

Open

2 tasks

Emin017 marked this pull request as ready for review January 9, 2026 10:38

Emin017 changed the title ~~Support nested build.mill files with relaxed package naming~~ Support nested build files with relaxed package naming Jan 9, 2026

lihaoyi reviewed Jan 10, 2026

View reviewed changes

example/large/multifile/12-import-subdir/build.mill Outdated Show resolved Hide resolved

lihaoyi reviewed Jan 11, 2026

View reviewed changes

example/large/multifile/12-import-subdir/build.mill Outdated Show resolved Hide resolved

lihaoyi reviewed Jan 11, 2026

View reviewed changes

example/large/multifile/12-import-subdir/build.mill Outdated Show resolved Hide resolved

Emin017 and others added 17 commits January 14, 2026 10:32

Fix duplicate file bug

fa7ddda

Signed-off-by: Emin <me@emin.chat>

Relax package validation for all nested build files

78beef0

Signed-off-by: Qiming Chu <cchuqiming@gmail.com>

Check conflicting build files in same directory

7d744f2

Signed-off-by: Qiming Chu <cchuqiming@gmail.com>

Add local build object for nested build files

5d81399

Signed-off-by: Qiming Chu <cchuqiming@gmail.com>

Reformat, NFC

1fca29a

Signed-off-by: Qiming Chu <cchuqiming@gmail.com>

Fix helper files relax validation

8c60314

Signed-off-by: Emin <me@emin.chat>

Use fully path for millDiscover reference

a5a70cf

Signed-off-by: Emin <me@emin.chat>

Update test assertion for fully millDiscover reference

ebef4f3

Signed-off-by: Emin <me@emin.chat>

Add documentation and examples for nested build files

7737464

Signed-off-by: Emin <me@emin.chat>

Refactor nested build file validation

191f2b8

Signed-off-by: Emin <me@emin.chat>

Extract nested yaml header parse to BuildHeaderUtil

b498461

Fix missing useDummy condition

946b8f8

Signed-off-by: Emin <me@emin.chat>

Add allowNestedBuildMillFiles in Evaluator

6b23e90

Signed-off-by: Emin <me@emin.chat>

Add allowNestedBuildMillFiles docs

3149460

Signed-off-by: Emin <me@emin.chat>

Allow root build file to enable nested builds globally

c7f0017

Signed-off-by: Emin <me@emin.chat>

Emin017 force-pushed the relax-pkg-naming branch 2 times, most recently from 03b8fa3 to 3f5933b Compare January 14, 2026 03:48

autofix-ci bot and others added 2 commits January 14, 2026 15:45

[autofix.ci] apply automated fixes

1ebda4c

fixup! Support nested build.mill files with relaxed package naming

f1fca50

Emin017 force-pushed the relax-pkg-naming branch from 3f5933b to 83d1e0f Compare January 14, 2026 07:54

Avoid prefixing parseBuildFiles for package.mill header errors

57b819d

Keep legacy `[error] [error] package.mill:...` output, aligned with YamlHeaderPackageTests. Signed-off-by: Emin <me@emin.chat>

Emin017 force-pushed the relax-pkg-naming branch from 83d1e0f to 57b819d Compare January 14, 2026 09:29

lihaoyi mentioned this pull request Jan 23, 2026

Allow nested build.mill files under a flag #6655

Merged

lihaoyi added a commit that referenced this pull request Jan 23, 2026

Allow nested build.mill files under a flag (#6655)

d773c6e

Fixed #5091, a second implementation of #6504

Emin017 closed this Jan 23, 2026

Uh oh!

Support nested build files with relaxed package naming #6504

Support nested build files with relaxed package naming #6504

Uh oh!

Conversation

Emin017 commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Relaxed Package Declarations

Relaxed Match Definition

Usage Example

Limitation

Uh oh!

inochisa commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Emin017 commented Jan 8, 2026

Uh oh!

inochisa commented Jan 8, 2026

Uh oh!

Emin017 commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

inochisa commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Emin017 commented Jan 8, 2026

Uh oh!

Emin017 commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

inochisa commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lihaoyi commented Jan 9, 2026

Uh oh!

inochisa commented Jan 9, 2026

Uh oh!

Emin017 commented Jan 9, 2026

Uh oh!

inochisa commented Jan 9, 2026

Uh oh!

Emin017 commented Jan 9, 2026

Uh oh!

inochisa commented Jan 9, 2026

Uh oh!

inochisa commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Emin017 commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lefou commented Jan 9, 2026

Uh oh!

inochisa commented Jan 9, 2026

Uh oh!

lihaoyi commented Jan 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Emin017 commented Jan 14, 2026

Uh oh!

lihaoyi commented Jan 23, 2026

Uh oh!

Emin017 commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Emin017 commented Jan 6, 2026 •

edited

Loading

inochisa commented Jan 8, 2026 •

edited

Loading

Emin017 commented Jan 8, 2026 •

edited

Loading

inochisa commented Jan 8, 2026 •

edited

Loading

Emin017 commented Jan 8, 2026 •

edited

Loading

inochisa commented Jan 9, 2026 •

edited

Loading

inochisa commented Jan 9, 2026 •

edited

Loading

Emin017 commented Jan 9, 2026 •

edited

Loading