Document how to access sub-modules from meta-build/src files

[lefou]

The initial issue was found. But there should be better documentation.

---

I'm in the process of refactoring a larger Mill build which manages lots of modules under meta-build/src to the newly added sub-modules approach. It looks like while I can access sub-module from other modules defined in build.sc or module.sc files, I can't access these modules from any .scala file under the meta-build/src directory.

Minimal Reproducer:

> tree
.
├── bar
│   └── module.mill
├── build.mill
└── mill-build
    ├── build.mill
    └── src
        └── FooModule.scala

4 directories, 4 files

// build.mill
package build

import $meta._
import $packages._
import mybuild.FooModule

object foo extends FooModule

// meta-build/build.mill
object `package` extends MillBuildRootModule

// bar/module.mill
package build.bar

object `package` extends RootModule with JavaModule

// meta-build/src/FooModule.scala
package mybuild

import mill._
import mill.scalalib._

trait FooModule extends JavaModule {
  def moduleDeps = Seq(build.bar)
}

mill resolve __
No mill version specified.
You should provide a version via '.mill-version' file or --mill-version option.
Using mill version 0.12.0
[mill-build/build.mill-57/61] compile
[mill-build/build.mill-57] [info] compiling 1 Scala source to /tmp/mill2/out/mill-build/mill-build/compile.dest/classes ...
[mill-build/build.mill-57] [info] done compiling
[build.mill-57/61] compile
[build.mill-57] [info] compiling 2 Scala sources to /tmp/mill2/out/mill-build/compile.dest/classes ...
[build.mill-57] [error] /tmp/mill2/mill-build/src/FooModule.scala:5:24: not found: value build
[build.mill-57] [error]   def moduleDeps = Seq(build.bar)
[build.mill-57] [error]                        ^
[build.mill-57] [error] /tmp/mill2/build.sc:4:20: not found: type FooModule
[build.mill-57] [error] object foo extends FooModule
[build.mill-57] [error]                    ^
[build.mill-57] [error] /tmp/mill2/build.sc:3:1: not found: value n
[build.mill-57] [error] n
[build.mill-57] [error] ^
[build.mill-57] [error] three errors found
[61/61] =============================================================================================================== resolve __ ================================================================================================================ 10s
1 tasks failed
compile Compilation failed

[lefou]

I think the correct way to reference the build module scope, from where we can access all other modules, is to import it as folows into the Scala source files:

import build_.{package_ => build}

This works in my project, but somehow not in my reproducer project, which for some reasons does not detect the bar module at all.

[lefou]

I think we need to provide more infos for users to debug their builds. E.g. print more when running with --debug and/or document what to inspect to see, why there are no detected modules...

[lefou]

I found the other issue causing the sub-package not being recognized. I used module.mill instead of package.mill for the sub-package.