First pass at first-class support for Java projects

[lihaoyi]

Most of the functionality necessary to support Java projects is already there, what's missing is a proper documentation and onboarding experience. This PR aims to make a first pass at writing that and setting up the supporting tooling necessary to do so. A Java programmer should be able to land on Introduction to Mill for Java, read through it, and competently make use of Mill for their Java project even without significant Scala expertise.

• Since the Scala and Java modules are pretty tied together via Zinc, for now I decided to avoid trying to split out a proper javalib module and left everything in place inside scalalib. Instead, I defined a package object javalib with a bunch of aliases pointing at the various scalalib functionality; this should give us the UX benefits of letting users import javalib._, without needing to invasively refactor the codebase. There's some tradeoff with scalalib still appearing in stack traces etc., but for a first pass I think that's fine.

• I added a new set of example/basicjava/, javamodule, and javabuilds.

  • These are duplicates of example/basic/, scalamodule, and scalabuilds, but for Java. I implemented a janky DIY build.sc templating/extension system, to allow me to share the bulk of the ascidoc between the Scala/Java versions while only specifying the differences: generally the build.sc Scala logic needs to be adapted, but the asciidoc text and the Usage command-blocks can mostly be re-used.

  • All of the Java versions of the examples have had their Scala code ported to Java. This includes third party libraries, e.g. replacing MainArgs with ArgParse4j, Scalatags with escapeHtml4 from apache commons text. Most of the Usage command-blocks testing the builds are shared between the Java and Scala versions of each example, although some had to be generalized a bit, and a handful only apply to a single language

  • The word "Scala" does not appear anywhere in the new documentation pages. In general, a Java programmer should be comfortable running through the docs, learning to use Mill, all without being scared off by it being a "Scala" build tool

• Moved the docs for the example/thirdparty/jimfs/ folder to the new Java Build Examples section, and added a new example/thirdparty/commons-io/ folder to also include in those docs

With this PR, the docs have roughly the following sections:

• Scala Quick Start: Scala Specific
• Java Quick Start: Java Specific
• Mill in Depth, Mill Plugins, Reference: Language Agnostic

In future, if we include Kotlin support, we can have a Kotlin Quick Start section next to that of the other two languages. It should be pretty easy (O(days)) to duplicate all the work I did for Java for Kotlin.

Doc changes can be reviewed locally via ./mill -i docs.localPages

Pull Request: #3261

[lihaoyi]

This is a binary compatible change, so we can merge it into main and cut a 0.11.9 (we should cut a release soon after merging, because the new docs get published immediately from master, and people will be confused if the code hasn't been published yet)

[lefou]

In the locally built page, I see strange markers like SNIPPED:BUILD. Are they necessary? Could you hide them with AscciDoc comments (//)?

[lihaoyi]

Ah that's probably a screw up in my templating logic, will fix

[lihaoyi]

Fixed it by swapping to asciidoc comments //// SNIPPET:

[lefou]

Do we really need that template logic? Can't we re-use AsciiDdoc includes here? Or do you already use them as tags for AsciiDoc includes? It's not obvious to me.

[lihaoyi]

Few reasons:

• We need to template not just asciisoc, but also the Using command blocks which are parsed separately to transform into asciidoc. So Asciidoc-level language features are not enough

• I want to keep the original build.sc mostly intact, so it can be read easily, which means i want some kind of inheritance/override mechanism, whereas using includes which would require breaking up the build file into reusable partials which would make them much harder to follow. Fundamentally this kind of templating is nothing new, and engines like Jinja2 have supported it forever, for good reason.

• We already do manual parsing of the build.sc to generate the asciidoc, so it felt natural to add a bit of additional logic rather than pulling in a heavyweight dependency (e.g. Jinjava) or breaking up every build.sc into reusable partials

The implementation of our hacky build.sc doc-generator is not pretty, but I think the DRYness and readability of the combined test logic and documentation has been very good, so it's worth suffering the hackiness

[lefou]

Why do we need two separate Installation pages for Java and Scala, while both contain the exact same content (via include)?

[lihaoyi]

Why do we need two separate Installation pages for Java and Scala, while both contain the exact same content (via include)?

Because I couldnt find a better place to put it, and having one page in both lists causes antora bugginess.

Fundamentally, i want people to read that as the second page, after they read the intro but before they read the rest. So putting it alone at the top as the landing page doesnt work, and putting it below the Java/Scala quickstarts doesnt work. But people using both languages need the same installation instructions, so I ended up putting it in both

[lefou]

Why do we need two separate Installation pages for Java and Scala, while both contain the exact same content (via include)?

Because I couldnt find a better place to put it, and having one page in both lists causes antora bugginess.

Fundamentally, i want people to read that as the second page, after they read the intro but before they read the rest. So putting it alone at the top as the landing page doesnt work, and putting it below the Java/Scala quickstarts doesnt work. But people using both languages need the same installation instructions, so I ended up putting it in both

We can just include a link to the same page in both sections, so we don't need the 3 files.

PS: I fixed some adoc includes

[lihaoyi]

I can convert it to a link

I wonder if there's some way to make asciisoc fail loudly if includes are not found. I find it very error prone looking for broken includes in the generated html

[lefou]

I can convert it to a link

I meant to revert to a single Installation_IDE_Support.adoc file and add it twice in the nav.adoc where needed.

I wonder if there's some way to make asciisoc fail loudly if includes are not found. I find it very error prone looking for broken includes in the generated html

I agree. I can ask @mojavelinux ...

[lihaoyi]

meant to revert to a single Installation_IDE_Support.adoc file and add it twice in the nav.adoc where needed.

Having the same page twicenin the adoc doesnt work because they are the same page, so regardless of whether you go to the Java or Scala version the next button will bring you to the same destination (IIRC the first one, so Scala???). That would be very confusing to a reader to have it switch language suddenly after 2 pages

[lefou]

meant to revert to a single Installation_IDE_Support.adoc file and add it twice in the nav.adoc where needed.

Having the same page twicenin the adoc doesnt work because they are the same page, so regardless of whether you go to the Java or Scala version the next button will bring you to the same destination (IIRC the first one, so Scala???). That would be very confusing to a reader to have it switch language suddenly after 2 pages

Ah, I didn't thought about the "next" button, which I use seldomly. It makes sense now.

[lefou]

I only found the opts=optional option, which makes the include:: no emitting a warning, but no way to throw an error. (https://docs.asciidoctor.org/asciidoc/latest/directives/include/#include-resolution).

I opened a question: https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/Make.20including.20a.20missing.20file.20a.20failure

Edit: Opened https://antora.zulipchat.com/#narrow/stream/282400-users/topic/How.20to.20fail.20when.20an.20included.20file.20can't.20be.20resolved

[lefou]

After my latest push, we now fail if xrefs or includes can't be resolved.

[lefou]

This file looks like a copy of Builtin_Commands.adoc and has some Scala mentions, for example in the init command. We should either share/include the identical content, or adapt it further.

[lefou]

We should rather provide a minimal Java skeleton project.

[lihaoyi]

I'm going to remove the init portion of this doc for now I think. I'd like to overhaul it at some point later to make it accept the various example projects as templates, but that can come in a follow up PR

[lefou]

Looks good to me. Let's welcome Java developers!

[lihaoyi]

Going to cut a 0.11.9 just to ensure the code is up to date with the docs