How I SBT - III

Previously, we discussed how to quickly write a simple build.sbt without fuss. We briefly understood how it is processed by SBT along with Settings and Tasks. We did that without having to know about the build folder structure¹ et al.; until now.

• How I SBT - build.sbt
• How I SBT - Settings & Tasks
• How I SBT - Plugins
• How I SBT - Build Code Organization

Build Folder Structure

Below is the project and build folder structure. There are two things that SBT is interested in your project - build.sbt and project/ ².

root of the project
├ src/main/scala/...
├ project/
  ├ build.properties
  ├ ...
├ build.sbt
├ .gitignore

The build.properties contains the sbt.version = x.y.z ³ to instruct the SBT to ensure that the aforementioned version of SBT is used for building your project. The sbt command by itself is a launcher to download / pick the relevant version of SBT.

In fact, build.sbt alone is enough for SBT to create the project/ folder. SBT creates build.properties automatically, if one does not already exist. Try it …

The project/ folder is where the Plugins also go!

Plugins

A Plugin is a way in SBT to add specific features or functionalities to the build. It allows adding code to customize and extend the build capabilities of your project; such as adding or updating Settings, defining new Tasks, code generation etc. Plugins may be shared across projects, if written in a generic enough way.

There are tons of community plugins. Here is a just glimpse of the popular ones:

• sbt-pack - A sbt plugin for creating distributable Scala packages
• sbt-dependency-graph⁴ - sbt plugin to create a dependency graph for your project
• sbt-docker - Create Docker images directly from sbt
• sbt-prompt⁵ - An SBT plugin for making your SBT prompt more awesome

There are dozens of very popular plugins that do different things. I just listed what came to my mind at the time of this writing.

To add a plugin to your project, add addSbtPlugin("org" %% "name" % "<version>") to project/plugins.sbt .

Using the name plugins.sbt is a convention. But it can be named anything as long as the extension is .sbt .

Add the following to project/plugins.sbt to add the docker plugin to your project.

addSbtPlugin("se.marcuslonnberg" % "sbt-docker" % "1.9.0")

You may add the desired plugins like mentioned above. Since sbt-dependency-graph is bundled with, you use the helper addDependencyTreePlugin ⁶.

Depending on the Plugin, you may have to enablePlugin ⁷ explicitly. Or they may be activated automatically. In other words, they will be executed without developer intervention.

Global.sbt

SBT files under ~/.sbt/1.0 are processed / loaded for all SBT projects on the machine. The convention is to create a global.sbt although you can name it anything, and create any number of sbt files.

So, if you addSbtPlugin in global.sbt, it will be made available for all SBT projects on your machine. Depending on the trigger (discussed below), the plugin may be automatically activated.

On my machine, in global.sbt, I have customizations for the prompt of my SBT shell.

Holy grail of SBT - Custom Plugins

Plugins by itself may be considered the Holy Grail of SBT. But custom Plugins is the cherry on top. It is easy and fun to write SBT Plugins. You don’t believe me. Try writing a Maven or Gradle plugin. 🙄

Alright, let us write one. The Plugin we are going to write is one that configures your build with a preset of compiler options. Imagine writing one for your company that all teams would have to use as a standard.

import sbt.*

object MyCompilerOptionsPlugin extends AutoPlugin {
  override def projectSettings: Seq[Setting[_]] = Seq(
    scalacOptions ++=
      "-encoding" ::
      "utf8" ::
      "-deprecation" ::
      "-feature" ::
      "-unchecked" ::
      "-Xlint:adapted-args" ::
      "-Xfatal-warnings" ::
      "-Wvalue-discard" ::
      // ... whatever else
      Nil
  )
}

Pardon the name. Otherwise, the plugin is pretty generic⁸. Let us dissect.

• There is hardly a need for more than one instance of our Plugin. Hence, we declare it as an object.
• Our Plugin extends AutoPlugin - the base type⁹ of Plugins, which provides the ability to enable it based on certain conditions. Or automatically. In our case, it is neither. We would explicitly enablePlugin in our build definition.

lazy val petStore =
  project
    .in(file("."))
    .settings(
      name := ...
      version :=  ...
      organization := ...
      scalaVersion := ...
    )
    // ENABLING THE PLUGIN HERE, which will update the settings
    // of this project with the compiler options set in the plugin
    .enablePlugins(MyCompilerOptionsPlugin)
    .settings(
       ...
    )

• If you like to automatically enable the plugin without having to explicit call enablePlugins then you would add this to our Plugin definition:

object MyCompilerOptionsPlugin extends AutoPlugin {
  override def trigger = allRequirements

  override def projectSettings: Seq[Setting[_]] = ...
}

• trigger controls when the Plugin is applied to the project
• allRequirements is a predefined value in SBT to apply our Plugin unconditionally to all projects in the build. Note that so far we are dealing with a single project.
• If we don’t specify the trigger value, SBT defaults it to a predefined noTrigger, which means it has to be explicitly enabled.
• Conditionally applying may be handled through enablePlugins or disablePlugins. The other option, which I don’t recommend, is through Plugin logic by bypassing if certain conditions don’t meet.
• There are cases where our Plugins may have to depend on others. Say you are going to wrap around the sbt-scalafmt for augmenting with whatever. In such a case, if the former was not applied, our Plugin would fail miserably. And will fail the build. SBT allows to capture such dependencies via requires.

import sbt.*
import org.scalafmt.sbt.ScalafmtPlugin

object MyCompilerOptionsPlugin extends AutoPlugin {
  override def requires = ScalafmtPlugin && plugins.JvmPlugin
  
  override def trigger = allRequirements

  override def projectSettings: Seq[Setting[_]] = ...
}

Plugin Scope

A Plugin may be configured to apply to the project or build. projectSettings get applied to every project in the build. So, they will be invoked once per project in the build. buildSettings get applied once for the entire build. In fact, you could add the settings in MyCompilerOptionsPlugin to the build in addition you could also add the scalaVersion, version, and organization. Because in all likelihood they will be the same for all projects in the build.

object MyCompilerOptionsPlugin extends AutoPlugin {
  override def requires = ...
  override def trigger = allRequirements

  override def buildSettings: Seq[Setting[_]] = Seq(
    version := "0.1.0-SNAPSHOT",
    organization := "hkt",
    scalaVersion := "2.13.15",
    scalacOptions ++= ... same options as before ...
  )
}

If that is the case, is there a need for projectSettings, you ask. Sure yes. There are project level settings to be applied such as library dependencies, compilation source and resources paths, settings for code generation specific to the project etc.

I am liberal in defining Plugins in my project. I group settings and throw them into a Plugin, make it as generic as possible, at least within the business domain .

Because a name speaks more than a bunch of settings. Don’t agree. Tell me what this does. You got one second 😄

resTask := {
  val resources = (Compile / resourceDirectory).value
  val managedResources = (Compile / resourceManaged).value
  val logger = streams.value.log

  (resources ** "*.txt").get.foreach { file =>
    val content = IO.read(file)
    val processedContent = s"# DO NOT EDIT\n\n$content"
    val targetFile = managedResources / file.getName
    IO.write(targetFile, processedContent)
    logger.info(s"Processed resource: ${file.getName}")
  }
}

However, if I create a PrependDoNotEditToTxtResourcesPlugin then the blob of logic is not that intimidating.

Order of loading Plugins

While this is important to know, in practice, the order should not matter much. Plugins tend to be fairly orthogonal in the functionality they add or augment. Our compiler options plugin has little overlap with say coverage plugin. But there are situations when you might see ordering problems such as _Setting_s assuming unexpected value. In such cases, knowing the ordering should come in handy.

There is an overall order in which plugins are loaded:

• Global plugins (~/.sbt/1.0)
• Plugins listed in order in project/plugins.sbt
• Auto plugins defined in project/ folder.
  • Automatic enabled plugins (trigger=allRequirments). Order of plugins loaded is not deterministic. If two plugins write to the same settings (say organization), the last one to write to the settings wins.
  • Plugins enabled in build.sbt in the order listed.

Cliffhanger

I think we can stop there for now. I believe you should be able to write Plugins now to your heart’s content. There’s more to Plugins that what I have talked about here. Refer the official documentation.

Looking back, you should be able to write a decent SBT build definition with Settings, Tasks, and Plugins ; built-in and custom. Remember my style / tip to write the build definition in a functional style.