Document project structure

[asarkar]

AFAICT, a recommended project structure for Mill is non-existent. As a new user, I'm faced with the following issues:

1. The Scala Days talk on YouTube doesn't demonstrate the use of any package or test directory.
2. There's a Hello World project made by Alvin Alexander.
3. There's a mill-scala-hello Gitter template.

2 and 3 differ substantially.

The Gitter template generates the following directory structure:

foo
├── build.sc
└── foo
    ├── src
    │   └── com
    │       └── example
    │           └── Hello.scala
    └── test
        └── src
            └── com
                └── example
                    └── HelloTest.scala

Although the top-level directory and the only Mill module are both named foo, it appears that this isn’t a requirement, and the top-level foo may contain multiple Mill modules named whatever necessary.

The package is under the src directories, and is com.example above.

This ticket asks that the following is clarified/documented:

1. A recommended single-module project structure including unit tests and a non-default package (i.e. files not directly under src). The assumption is that a multi-module project is simply a collection of several single-module (potentially interdependent) projects.
2. Separation of Java and Scala source code in a mixed project.
3. Separation of unit and integration tests in a multi-module project.
4. Separation of main and test resources.

A screenshot from the Scala Days talk is shown below as evidence that it doesn't answer any of the questions above.

[lihaoyi]

The recommended project templates are in the docs. There are quite a number of examples. Anything else is left up in the air, and I don't think there is consensus on a lot of it e.g. the folder layout within src/.

If you wish to discuss it you can open a thread on the discussions forum, but most of the decisions you brought up are basically out of scope for Mill as of today

[lihaoyi]

https://mill-build.com/mill/Scala_Build_Examples.html

[asarkar]

I've studied the examples before opening the ticket, and they don't answer the questions posed above. I don't understand how these questions can be out of scope, because the tool would have it's own opinion about the structure. Sure, the structure can be customized, but that, by definition, means deviating from the default, and the default is unclear (to me).

[lefou]

I tried to address your questions in the other answer (#2913 (comment)). If you have an idea, where exactly in the documentation some more details are needed, please point it out or open a PR.

[lefou]

Welcome to Mill!

I guess, the Giter8 template already shows an idiomatic project layout. Except, it does not use the RootModule, which was introduces in Mill 0.11, and which can ease the case of a single top level module.

Here is the out-of-the-box layout of the Giter8 template.

foo
├── build.sc
└── foo
    ├── src
    │   └── com
    │       └── example
    │           └── Hello.scala
    └── test
        └── src
            └── com
                └── example
                    └── HelloTest.scala

If you change it as follows

-object foo extends ScalaModule {
+object foo extends RootModule with ScalaModule {

the resulting layout will avoid the extra nested foo directory resembling the single top level module.

foo
├── build.sc
├── src
│   └── com
│       └── example
│           └── Hello.scala
└── test
    └── src
        └── com
            └── example
                └── HelloTest.scala

Please keep in Mind that Mill itself is a general purpose build tool which enbeds it's project definition into a Scala script and provides rich generic features like caching or introspectability.

You can customize the opinionated modules provided in scalaib / scalajslib / scalanativelib or completely write your own.

IMHO, we show a lot of examples in the docs, and there is also the Mill project's own build.sc as a guidance.
But as you said, maybe we can put some more info here and there.

• A recommended single-module project structure including unit tests and a non-default package (i.e. files not directly under src). The assumption is that a multi-module project is simply a collection of several single-module (potentially interdependent) projects.

This is essentially what the Giter8 template provides. To have another module, just duplicate the foo object to a new name bar and you're done. But your assumption is probably incorrect, once you start using RootModule.

• Separation of Java and Scala source code in a mixed project.

This isn't enforced by the modules in scala{,js,native}lib. But a JavaModule would only compile Java files, while a ScalaModule will correctly handle compilation of Java and Scala files under src, even if they call each other. (Nothing stops you from changing the accepted source folder and split you files by language though.)

• Separation of unit and integration tests in a multi-module project.

This is easy. As test (sub)modules are ordinary modules, you can just create more of them and name them it or itest.

• Separation of main and test resources.

This is already the case. By default, resources are located in the resources folder of the module. The resources of foo are located under foo/resources, and the test resources of foo.test are under foo/test/resources. We even differentiate between compile-time (foo/compileResources) and runtime resources.

[gl-yziquel]

Sigh... The only way I got the RootModule to work out as expected was the following:

In build.mill:

import mill._, scalalib._

object `package` extends RootModule with ScalaModule {
  def scalaVersion="2.13.14"
}

This is underdocumented. mill complains about the package not being package, but getting to understand I was missing the backticks... Made me loose a whole working day.

Anyhow...

Examples do matter.

[lefou]

The documentation site by default addresses the latest stable Mill version, which is 0.11.12 as of today. To read the documentation for the upcoming Mill 0.12.0, which is still not finalized, you need to select the respective version on the documentation page (in the top right corner). You will find a lot of examples for each supported language.

[gl-yziquel]

@lefou ah... yes... I have a bad habit of building everything from source from git HEAD. Apologies.