18. From scala-cli to sbt

Fully Booked is thirty-nine Scala files in one directory. Each can see all the others and is compiled against the same list of libraries, so the booking rules from chapter 3 have Cats Effect, fs2 and Ox on their classpath for no reason. The scala command has no way to split a project into parts with their own libraries, and Part IV is about to add an HTTP layer and a database.

sbt is the build tool most Scala projects use. We’ll move the project to it and split the code into three parts with their own dependencies. Then we’ll make warnings into errors, set up formatting, and have a build server run the checks on every change. The build in this book is on sbt 2. Most of what’s been written about sbt describes version 1, so I’ve pointed out where the two differ in something you’re likely to read about.

18.1. sbt and a JDK

If you installed Scala with cs setup in chapter 1, you already have an sbt command. If not, the installation page at https://www.scala-sbt.org has the options. The sbt command is only a small launcher. Each project names the version of sbt it wants, and the launcher downloads that version the first time it’s needed.

sbt doesn’t fetch a JDK the way //> using jvm 25 did. It uses the JDK that JAVA_HOME points to, or the first java on your path if JAVA_HOME isn’t set, so check that the one it will find is version 25. If it isn’t, Coursier can supply JDK 25 for the current terminal on macOS or Linux:

$ eval "$(cs java --jvm 25 --env)"

To make the change permanent, run cs java --jvm 25 --setup. Running our programs needs Java 23 or later, because the JVM option we’ve been passing since chapter 6, --sun-misc-unsafe-memory-access=allow, doesn’t exist before that. An older JVM won’t start when it’s given an option it doesn’t know.

18.2. Three subprojects

sbt calls the parts of a build subprojects. Ours will be:

  • core, the code with no effects in it: the model, the rules, validation, the in-memory store and the command-line entry points from Parts I and II. It needs only Cats.

  • service, everything written against IO: configuration, the journal, concurrency, confirmations and the import. It needs core, Cats Effect, fs2, PureConfig and logging.

  • direct, chapter 17’s code. It needs core and Ox.

sbt expects the directory layout that Maven uses, with code under src/main/scala, tests under src/test/scala and other files under src/main/resources. From the top-level directory of the project, on macOS or Linux, these commands put everything where it belongs:

mkdir -p core/src/main/scala core/src/test/scala
mkdir -p service/src/main/scala service/src/main/resources service/src/test/scala
mkdir -p direct/src/main/scala direct/src/test/scala

mv direct.scala direct/src/main/scala/
mv direct.test.scala direct/src/test/scala/

mv bigfile.scala concurrency.scala config.scala confirmations.scala service/src/main/scala/
mv evening.scala importer.scala journal.scala service.scala service/src/main/scala/
mv concurrency.test.scala confirmations.test.scala service/src/test/scala/
mv effects.test.scala streams.test.scala service/src/test/scala/
mv resources/* service/src/main/resources/

mv *.test.scala core/src/test/scala/
rm project.scala
mv *.scala core/src/main/scala/
rmdir resources

On Windows, make the same moves in Explorer. The tests keep their .test.scala names, but under sbt a file is a test because of the directory it’s in. project.scala goes because sbt doesn’t read directives. nightly.csv stays where it is, because sbt runs our programs from the top-level directory.

18.3. The build definition

The version of sbt goes in project/build.properties, a file of a single line:

sbt.version=2.0.12

The build itself is described in build.sbt. It goes at the top level, beside nightly.csv, and not in the new project directory:

scalaVersion := "3.9.0"
organization := "com.fullybooked"
version := "0.1.0"

run / javaOptions += "--sun-misc-unsafe-memory-access=allow"

val munit = "org.scalameta" %% "munit" % "1.3.6" % Test

lazy val core = project
  .settings(
    libraryDependencies ++= Seq(
      "org.typelevel" %% "cats-core" % "2.13.0",
      munit
    )
  )

lazy val service = project
  .dependsOn(core)
  .settings(
    libraryDependencies ++= Seq(
      "org.typelevel" %% "cats-effect" % "3.7.1",
      "co.fs2" %% "fs2-io" % "3.14.0",
      "com.github.pureconfig" %% "pureconfig-core" % "0.17.11",
      "org.typelevel" %% "log4cats-slf4j" % "2.8.0",
      "ch.qos.logback" % "logback-classic" % "1.6.7",
      munit
    )
  )

lazy val direct = project
  .dependsOn(core)
  .settings(
    libraryDependencies ++= Seq(
      "com.softwaremill.ox" %% "core" % "1.1.0",
      munit
    )
  )

The scala command can write a file like this for you. The command is scala --power export --sbt . and it’s marked experimental. When I tried it on this project the result needed enough tidying that I wrote the file by hand.

A build.sbt is Scala with a few operators of sbt’s own. Things that sbt does, such as compile or test, are called tasks. Most of the file is a list of settings, the values those tasks work from. Each setting gives a value to a key: := sets it, += adds one element to a key that holds a list and ++= adds several. The dependencies are the ones project.scala listed, with the parts of each joined by %. The doubled %% does what :: did in a directive and picks the build of a library for our version of Scala. A % Test on the end keeps the library to the tests, as test.dep did.

Each lazy val ... = project declares a subproject in the directory of the same name. A lazy val is a val that isn’t worked out until it’s first used. sbt’s documentation uses one here so that subprojects can refer to one another in any order. The dependsOn(core) on service and direct puts core and its libraries on their classpaths. Neither of those two can see the other.

In sbt 2 a setting written at the top, outside any subproject, applies to every subproject. In sbt 1 such a setting didn’t reach the subprojects, which is why older builds write ThisBuild / scalaVersion. The slash in run / javaOptions narrows a key: these are the JVM options for running our programs, and not for the compiler or the tests.

Now compile:

$ sbt compile
[error] -- [E006] Not Found Error: .../fully-booked/direct/src/main/scala/direct.scala:23:20
[error] 23 |  def first = reply(ibrahim.name, reserve(store, ibrahim, eight))
[error]    |                    ^^^^^^^
[error]    |                    Not found: ibrahim
[error]    |
[error]    | longer explanation available when compiling with `-explain`
...
[error] 15 errors found

The first run is slow, because sbt downloads itself and compiles the build definition before it looks at our code. The fifteen errors that follow are all in direct. Its code uses ibrahim, castellanos, eight and regulars from concurrency.scala, and that file now lives in service, which direct isn’t allowed to see. Above the errors is a warning that begins multiple main classes detected. sbt prints it whenever it compiles a subproject with more than one entry point, and you can ignore it. The output shown in this chapter leaves it out.

Both service and direct use those four values, so they belong in core. Cut them from service/src/main/scala/concurrency.scala, from val eight to the end of regulars. Paste them at the end of core/src/main/scala/tonight.scala and compile again:

$ sbt compile
[success] elapsed time: 2 s

A file in core that imports cats.effect.IO won’t build any more. The booking rules can’t pick up a dependency on chapter 20’s database driver either, unless somebody edits build.sbt to allow it.

18.4. Running things

$ sbt projects
[info] In file:.../fully-booked/
[info] 	   core
[info] 	   direct
[info] 	 * fully-booked-root
[info] 	   service
[success] elapsed time: 2 s

There are four subprojects, because the directory itself is one. That fourth one is called the root, and ours has no code in it. A task run without a name in front goes to the root, which passes it on to the other three, so sbt test tests everything. sbt core/test tests only core. These are the last two of about thirty lines:

$ sbt core/test
[info] Passed: Total 35, Failed 0, Errors 0, Passed 35
[success] elapsed time: 2 s

Run the same command again:

$ sbt core/test
[info] Passed: Total 0, Failed 0, Errors 0, Passed 0
[info] No tests to run for core / Test / testQuick
[success] elapsed time: 2 s

In sbt 2, test only runs the tests that failed last time, have never run, or depend on code that has changed. sbt keeps the results on disk, so it still knows them after the machine restarts. To run every test regardless there’s testFull.

sbt has also been running as a server since the first sbt compile, with the build loaded and the compiler warm, and each later command connects to it. You stop it with sbt shutdown. That’s also the thing to try if sbt stops noticing an edit to build.sbt, or fails without saying why: a new server reads the file afresh and prints the real error. Typing sbt alone opens a prompt on the same server, where ~test re-runs the affected tests every time you save a file.

To run a program, name its subproject and its entry point. I’ve put the next command in quotes so that the shell hands it to sbt as one piece. sbt 2 insists on that for a list of commands, as in sbt "clean ; compile ; test", where sbt 1 accepted sbt clean compile test.

$ sbt "service/runMain fullybooked.ImportBookings"
18:30 table 3: Hughes, party of 4
19:00 table 1: Banerjee, party of 2
Line 3: 'six' isn't a number of people
19:30 table 4: Kowalczyk, party of 3
Line 5: we need a name for the booking
20:00 table 6: Mbeki, party of 8 (deposit taken)
Line 7: no table for 8 is free at 20:00
Line 8: '7pm' isn't a time, try 19:30; 'call the hotel' isn't a phone number
INFO  ImportBookings: Imported 4 bookings from nightly.csv
[success] elapsed time: 2 s

With no name, sbt service/run lists the entry points and asks which one you want. An sbt 1 build has a target directory in each subproject. In sbt 2, compiled classes go under target/out at the top level, with a subdirectory for each subproject.

18.5. Warnings as errors

In chapter 3 I said I tend to make all of my warnings hard errors. I do it because a warning that doesn’t stop the build is easy to scroll past. A project that lets warnings pile up can end with hundreds, and the one that matters is somewhere among them. Add this block to build.sbt after the first three lines. It asks the compiler for more warnings than it gives by default:

scalacOptions ++= Seq(
  "-deprecation",
  "-feature",
  "-Wunused:all",
  "-Wvalue-discard",
  "-Wnonunit-statement",
  "-Winfer-union"
)

The first two options, -deprecation and -feature, make the compiler spell out warnings it otherwise only counts. -Wunused:all reports imports, parameters and local values that nothing uses. -Wvalue-discard and -Wnonunit-statement catch a value being thrown away: one looks at places where a Unit was expected, the other at an expression on a line of its own in the middle of a block. -Winfer-union is behind the complaint we’re about to see. There’s also -Wall, which I don’t use on Scala 3.9. It includes a warning for every object other than a String inside an interpolated string, such as a LocalTime, and this project has about twenty of those.

The task Test/compile builds the tests as well as the main code. Start with core, which has one complaint:

$ sbt core/Test/compile
[warn] -- [E225] Type Warning: .../fully-booked/core/src/main/scala/main.scala:13:38
[warn] 13 |      val phone = booking.party.phone.getOrElse("none given")
[warn]    |                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[warn]    |A type argument was inferred to be union type fullybooked.Phone | String
[warn]    |This may indicate a programming error.

That’s the line in lookUp that chapter 8 left alone. It compiled because getOrElse was allowed to answer Phone | String, the union type chapter 10 explained. The compiler now says that a union it had to infer is probably a mistake. It’s right about this one, because the number prints without its space. Change the line to val phone = booking.party.phone.map(_.formatted).getOrElse("none given").

Now run sbt Test/compile, which compiles the other two subprojects. They have four warnings between them. The compiler only reports a warning when it compiles the file, so running the same command a second time prints none of them.

  • In effects.test.scala, the lambda error => IO.pure(0) never uses error. Write _ => IO.pure(0).

  • In manyThreads, in direct.scala, the lambda’s last line is seated.incrementAndGet(). That call returns an Int, which is thrown away because a Runnable returns nothing. Write seated.incrementAndGet(): Unit, which tells the compiler that the value is being dropped on purpose.

  • In direct.test.scala, the two fork: blocks in the scope test each return a Fork that nothing uses. Ox’s discard method says that’s intended. Change the file’s import of Ox to import ox.{discard, fork, mapPar, sleep, supervised}. Then put .discard on a line of its own after each block, at the same indentation as its fork:.

With those fixed, add "-Werror", as the first line of the list and compile once more:

$ sbt Test/compile
[success] elapsed time: 2 s

With -Werror in the list, a compiler warning now fails the build.

18.6. Formatting

Scala’s formatter is scalafmt. I’d sooner have a tool decide the layout than discuss it in code review. sbt runs scalafmt through a plugin, and plugins are declared in project/plugins.sbt:

addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.6.2")

The formatter’s own settings go in .scalafmt.conf at the top level, beside build.sbt:

version = 3.11.5
runner.dialect = scala3
maxColumn = 100
align.preset = none

The version is there so that everyone’s files come out the same, and the dialect so that scalafmt expects Scala 3 syntax. For the other two I’ve gone against the defaults. I’ve raised the line length from 80, and I’ve stopped scalafmt lining up the arrows of neighbouring cases, although the book’s code has lined them up until now. With alignment on, one long pattern pushes every arrow in the block across the page and a one-line change shows up in a diff as five.

$ sbt scalafmtCheckAll
[warn] scalafmt: .../fully-booked/core/src/main/scala/desk.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/display.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/errors.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/events.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/model.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/phone.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/request.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/core/src/main/scala/tonight.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/direct/src/main/scala/direct.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/direct/src/test/scala/direct.test.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/service/src/main/scala/concurrency.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/service/src/main/scala/confirmations.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/service/src/main/scala/service.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/service/src/test/scala/confirmations.test.scala isn't formatted properly!
[warn] scalafmt: .../fully-booked/service/src/test/scala/streams.test.scala isn't formatted properly!

The errors that follow the list of files aren’t shown here. scalafmtCheckAll changes nothing and fails if any file would be changed, which is the form a build server wants. The reformatting is done by sbt "scalafmtAll ; scalafmtSbt", where the second task is for build.sbt itself. Run that command and check again, this time with scalafmtSbtCheck for build.sbt as well:

$ sbt "scalafmtCheckAll ; scalafmtSbtCheck"
[success] elapsed time: 2 s

That rewrote fifteen of your files. Have a look at what changed in tonight.scala and events.scala. If the project is in Git, commit the reformatting on its own, so that later changes aren’t buried in it. Metals and IntelliJ both read .scalafmt.conf and can format a file when you save it.

18.7. A build server

A build server is another machine that runs the same checks on every change. This workflow for GitHub Actions goes in .github/workflows/ci.yml at the top level:

name: CI
on:
  pull_request:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the code
        uses: actions/checkout@v6
      - name: Set up Java
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: 25
          cache: sbt
      - name: Set up sbt
        uses: sbt/setup-sbt@v1
      - name: Check formatting, compile and test
        run: sbt "scalafmtCheckAll ; scalafmtSbtCheck ; test"

The last step does the checking, with one sbt command made of the two formatting checks and the tests. The compiler options need no step of their own, since a warning already fails the compile that test depends on.

The setup-sbt action keeps sbt’s cache between runs, so with test in the workflow a test whose code hasn’t changed may not run again on the server either. Use testFull in the workflow if you want every test run on every change.

A .gitignore at the top level keeps the build’s output, and the files our programs write, out of the repository:

target/
.bsp/
.scala-build/
.metals/
.idea/
journal.log
big.csv

18.8. Exercises

There are no solutions to download for this chapter. The finished build is under ch18/project.

  1. Run one suite with sbt "core/test fullybooked.PhoneTests", twice. Then change an assertion in phone.test.scala so that it fails, and run sbt core/test twice more. Which tests ran each time?

  2. Add an unused import to a file in core, compile, and read what the compiler says. Then add import cats.effect.IO to the same file and compile again.

  3. sbt "show core / scalacOptions" prints the value of a setting, and sbt core/dependencyTree shows where each library on the classpath came from. Find out which version of the Scala library Cats was built against.

  4. Move bigfile.scala into a fourth subproject called tools that depends on service. What’s the least it needs in build.sbt?

  5. Change align.preset to more in .scalafmt.conf, reformat, and look at desk.scala. Put it back afterwards.