A plugin to reduce the boilerplate in many of the simpler laserdisc projects (but can be used in any sbt project).
It auto-configures things like sbt & scala versioning, cross compiling, scalafmt & git configuration and more.

See what it does for full details.

Add the following to project/plugins.sbt :

addSbtPlugin("io.laserdisc" % "sbt-laserdisc-defaults" % LATEST-VERSION-HERE)

// note: this plugin brings in sbt-scalafmt, sbt-git and sbt-native-packager automatically!

Then, in your build.sbt enable the plugin (either on the single project it contains, or in the case of a multi-module build, the root project)

lazy val root = (project in file("."))
	// other project configuration 
	.enablePlugins(LaserDiscDefaultsPlugin)

Note Any settings in your build.sbt override those set by this plugin.

When SBT loads your project, the LaserDiscDefaultsPlugin will automatically perform the following:

Adds Additional Plugins

• sbt-scalafmt - for applying formatting standards automatically to source code
• sbt-git - automatic versioning based on the current commit hash/tag
• sbt-native-packager -

Apply Core Settings

• Apply a bunch of default values:

  • scalaVersion to a recent version
  • organization to io.laserdisc
  • organizationName to LaserDisc

• Add some common command aliases:

  • sbt format - formats all Scala and SBT sources (According to .scalafmt.conf, see below)
  • sbt checkFormat - ensures all Scala and SBT sources are formatted correctly
  • sbt build - shortcut for checkFormat, clean, then test
  • sbt release - shortcut for build (above) then publish.

Apply Compiler Settings

• Sets the compiler to build for scala 3. This can be changed using CompileTarget:

  • import laserdisc.sbt.CompileTarget
    
    ThisBuild / laserdiscCompileTarget := CompileTarget.Scala2Only   // builds only for scala 2
    ThisBuild / laserdiscCompileTarget := CompileTarget.Scala3Only   // builds only for scala 3 (default) 
    ThisBuild / laserdiscCompileTarget := CompileTarget.Scala2And3   // cross compile both

    Remember that you need to use + in front of compilation-triggering tasks to trigger cross-compilation. The build alias added by this plugin automatically invokes +test.
• Apply our standard set of scalacOptions compiler and linting configurations (for each scala version).
  • This includes -Xfatal-warnings which fails the build by default if warnings are present.
    • This can be disabled via two mechanisms:
      • set ThisBuild / laserdiscFailOnWarn := false in the top level of your build.sbt (don't check this in!)
      • passing -DlaserdiscFailOnWarn=false as a SBT option (useful for local dev)
  • For Scala 2, this includes the better-monadic-for and kind-projector compiler plugins, which aren't necessary for Scala 3.

Generate .gitignore

• This file should be checked in (for instant IDE support when opening the project before sbt has initialized)
• The templating source is the .gitignore that configures this project.
• It is possible to disable this functionality (temporarily, please!) by doing the following
  • Set ThisBuild / laserdiscGitConfigGenOn:=false in the top level of your build.sbt
  • Pass -DlaserdiscGitConfigGenOn=false as a SBT option

Generate .scalafmt.conf

• This file should be checked in (for instant IDE support when opening the project before sbt has initialized)
• The templating source is the .scalafmt.conf that configures this project.
• It can be useful to disable this generation when trialing new scalafmt configurations locally.
  • However, please commit updated configurations to this project to maintain consistency!
  • Set ThisBuild / laserdiscScalaFmtGenOn:=false in the top level of your build.sbt
  • Pass -DlaserdiscScalaFmtGenOn=false as a SBT option

Set/Upgrade the sbt version in project/build.properties

• This file should be checked in.
  • You should reload sbt if the plugin changes the sbt.version value
• The templating source is this plugin's project/build.properties file.
• If the sbt.version in the consuming project is newer that what is in project/build.properties, the file will not be templated.
  • However, be a good citizen in that case, and upgrade sbt in this project so others get the upgrade!
• Set ThisBuild / laserdiscSBTVersionGenOn:=false in the top level of your build.sbt to disable this functionality (only if it causes issues).

Validate compliance with LaserDisc Standards Settings

• Fails the dist task if CODEOWNERS file is missing or empty.

Draft a new release, ensuring the format of the release follows the v1.2.3 format (note the v prefix), and the appropriate Github Action will publish version 1.2.3 (without the v) to sonatype.

An SBT plugin is developed as an SBT project just like a regular scala app, but some notes for anyone wanting to contribute:

• It helps to have some familiarity with using existing scala plugins

• The statement sbtPlugin := true causes SBT to configuring this project to build as a plugin.

  • One of the implications of this is that you are limited to Scala 2.12.x usage (sbt itself is currently built against 2.12)

• Testing is a little different than what standard projects use:

  • The scripted test framework provides a scripted command, that runs the plugin tests (instead of test)
  • Each plugin test is an actual sbt project configured in a particular way, with a set of assertions
  • Change scriptedBufferLog := false in build.sbt to show full test output when troubleshooting tests

• As you start to develop new defaults, understand the distinction between buildSettings and projectSettings

  • This plugin primarily defines the more global buildSettings
  • I have attempted to break down the functionality by area to keep things tidier, so check out the DefaultsCategory trait and its implementations to see how the current configuration is applied.

• One common gotcha is trying to access someSetting.value outside of a task or setting macro

  • those values are only available when SBT computes its task graph

    val optionKey = settingKey[Boolean]("Enable secret option")
    
    // fails with "`value` can only be used within a task or setting macro.."
    val allowSecretOption = optionKey.value  
    scalacOptions ++= {
       if (allowSecretOption) Seq("-Xallow-secret-feature") else Seq()
    }
    
    // access the value _inside_ the definition
    scalacOptions ++= {
      val allowSecretOption = optionKey.value
      if (allowSecretOption) Seq("-Xallow-secret-feature") else Seq()
    }

  • Even accessing the logger (Keys.sLog) requires use of value:

      Keys.sLog.value.info("foo") // must be inside a task/setting macro!

This plugin was developed by @barryoneill

In addition to creating issues on this repo, please use the #laserdisc slack for discussion about this plugin!