scala-maven-plugin: compiling Scala inside a Maven build

A Maven plugin, and the name it used to have

The scala-maven-plugin, previously maven-scala-plugin, is used for compiling, testing, running and documenting Scala code in Maven. That single sentence covers the whole scope, and it is worth sitting with the word plugin.

A plugin is not a build system. It is a set of goals bound into a lifecycle that already exists, and that has consequences for how it is used and how it fails. The plugin does not define your project layout, it does not manage your dependencies, and it does not give you a dependency resolution strategy of its own. It compiles Scala, and it wires the Scala-specific steps into a Maven build that someone else designed.

The rename is a small historical detail that matters for anyone searching for it. The old maven-scala-plugin name is still what many blog posts and older build files refer to, and knowing that the two names are the same project saves an afternoon of looking at an abandoned repository.

The primary language of the repository is Java, the licence is the Unlicense, and the default branch is master. The homepage for the project documentation is https://davidb.github.io/scala-maven-plugin/, and the README also points at a wiki and an issue tracker.

The Maven Central badge names the group as net.alchim31.maven and the artifact as scala-maven-plugin, which is the coordinates you put in your pom.xml.

Four goals, and what they mean for a Maven lifecycle

The four verbs in the description are the plugin's entire feature surface, and each maps to a distinct kind of work.

Compiling is the core one. Scala compiles to JVM bytecode, and unlike Java, the compiler is a separate program that has to be located, invoked, and given a classpath. Doing that inside a Maven build means dealing with the Scala compiler jar, the Scala library version, the plain scalac or Zinc decision, the Scala version versus the JDK version matrix, and the fact that the compiler needs the same dependencies as the code it compiles. A plugin that handles that is saving you a real category of work rather than saving you keystrokes.

Testing means running the Scala test framework as part of the build. Running means launching a main class or a script, which is what a build does for an application rather than a library. Documenting means generating scaladoc, which is a different tool from javadoc and needs its own configuration.

Each of those has to be bound to a Maven phase, and each has a set of parameters for the Scala version, the compiler arguments, the plugin repositories, the JVM fork options, and the arguments to pass through. That parameter surface is where a plugin like this either earns its place or becomes something nobody can configure.

The samples directory in the repository carries a multi-module example, and the documentation site is generated from the project itself, which means the reference for the parameters is the same artifact you would find by reading the plugin's own configuration classes.

Building the plugin, and the JDK 8 requirement

The Build section is short and has one detail that catches people: currently, you need Maven 3.x and JDK 8 to build the plugin, create the site, and run the integration tests.

JDK 8 for a plugin that compiles Scala is not a strange choice, and it is a deliberate one. The plugin runs inside Maven, and the oldest and widest range of Maven installations run on Java 8, so building the plugin against that baseline is what lets it be installed into the most existing builds. The corollary is that the plugin itself is not what constrains your Scala or your JDK version, since it invokes the compiler you point it at rather than embedding one.

The repository root has the Maven wrapper, mvnw and mvnw.cmd, so the build does not depend on a Maven being installed at all. The commands are all run through that wrapper.

./mvnw package
./mvnw site
./mvnw integration-test
./mvnw integration-test -Dinvoker.test=test1

The first of those generates the jar, the second generates the plugin website, the third runs the package step plus all of the integration tests, and the fourth runs a single integration test, test1, against all configuration, which the documentation describes as useful for tuning and debugging.

One test needs a local setting. To run test_scalaHome, you have to set the scala.home property in src/it/test_scalaHome/pom.xml to correspond to your environment, and the Build section is referenced for a simple setup of that.

The install path is ./mvnw install, which is the integration test run plus a publish to your local Maven repository, and it can be shortened with ./mvnw install -Dmaven.test.skip=true if you want neither the unit tests nor the integration tests to run.

The release process, and why it is manual on purpose

The release section of the README is long and detailed, and reading it tells you how the project is run.

The release chain is ./mvnw release:clean and ./mvnw release:prepare and ./mvnw release:perform, which publishes to the staging repository via the plugin. A second form adds skip tests and a skip of maven tests to publish without tests, and the reason given is right there in the text: integration test require 30min on CI.

That single fact is worth pausing on. The integration tests are slow enough that a release on CI would take half an hour, which is why the normal path runs them and the fast path does not. A project that publishes an artifact to Maven Central with a half-hour test suite is doing something that most plugin projects do not.

There is also a fully manual variant that runs a long list of goals in one command, including site, package, source:jar, javadoc:jar, install:install, gpg:sign, deploy:deploy and changes:announcement-generate, with the test-skipping flags and a performRelease flag.

The signing step is handled separately, and the reason is a specific macOS failure. The command is gpg --use-agent --armor --detach-sign --output $(mktemp) pom.xml, and the note is to avoid an issue on macOS with the gpg signature, with a link to the Apache JIRA entry for the GPG Plugin failing with Inappropriate ioctl for device.

After the deploy, the release is closed manually on the staging repository at oss.sonatype.org, and then the updated site is checked, with the version in the samples updated as well. The releases list in the repository is empty of GitHub releases, which is consistent with a project distributed through Maven Central rather than through GitHub release artifacts.

The alternatives, and the honest TODO list

The README names three similar plugins, and the difference in approach is what makes the choice.

The scalor-maven-plugin is a separate Maven plugin for Scala, the sbt-compiler-maven-plugin and the sbt-delegate-maven-plugin take different approaches to how sbt is involved. Those are three different amounts of commitment to sbt, and the third is the interesting one, because it is the same trade this plugin makes in the other direction.

The scalor-maven-plugin style of integration keeps Maven as the build system and adds Scala as a step inside it. The sbt-delegate approach and the sbt-compiler approach represent different points on that spectrum of involving sbt.

The other comparison is sbt itself, which is not a Maven plugin at all but the build tool the Scala ecosystem is designed around. The difference is not stylistic. sbt understands Scala's incremental compilation model natively, so it can recompile only what changed, and it has a plugin ecosystem for Scala-specific tooling. A Maven-based build recompiles through a compiler invocation on the whole module, which is exactly the kind of thing sbt was built to avoid.

The TODO section is a good honesty check on the project. It lists closing issues from the tracker, and a refactor with three items: reduce copy-paste, file path management can be improved a lot, and clean the code. A long-standing plugin with a public TODO acknowledging that its file path handling is weak is telling you something useful before you adopt it rather than after.

For an existing Maven-based Scala project, the practical question is not whether this plugin is better than sbt in the abstract, it is whether the cost of migrating your build is higher than the cost of keeping it.

Editorial conclusion

Adopt scala-maven-plugin if your Scala project is already on Maven and you want the compiler, scaladoc, test and run steps wired into the same lifecycle as the rest of your build. Do not adopt it if you are starting a new Scala project with no build tool, because sbt is the tool the Scala ecosystem is built around and this plugin exists to serve an existing Maven setup. Before you build the plugin from source, note that it needs Maven 3.x and JDK 8, and that the last push was recent with no GitHub releases, so the plugin is consumed from Maven Central rather than from a tagged artifact.

Frequently asked questions

Official sources

1. davidB/scala-maven-plugin on GitHub
2. Issues
3. License: Unlicense
4. Project website
5. README