sbt settings for beginners

sbt is a build tool used by many Scala projects. Developers using sbt will rarely need to know more than the basic commands like run, compile and test. But if you’re curious, you might want to learn more about how sbt works. If so, then this article series is for you!

Here, we learn about settings. First, let’s find out what they are and then we’ll do a practical exercise adapted from one that Eugene Yokota kindly gave to me. Let’s go!

First, what is a setting?

A setting expression contains helpful information for sbt to build our project. For example, the name and Scala version of our project.

Settings are evaluated only once on project load and are never re-run.

Here is an example of some settings declared in a build.sbt file:

lazy val root = (project in file("."))
  		.settings(
    			name := "Hello World",
    			scalaVersion := "2.13.1"
  	        )

build.sbt is a Scala based Domain Specific Language (DSL).

In this DSL, settings consist of a key (name and scalaVersion in the example above), an operator, which in this case is := and the setting body which is what the key evaluates to. For the name key the setting body is Hello World Project.

Let’s learn more about settings by creating our own setting expression in the exercise below.

Let’s do an exercise

In the terminal, create a new directory:

mkdir sbtSettings

inside our directory, let’s create a new file and name it build.sbt:

cd sbtSettings
touch build.sbt

edit the build.sbt file in the code editor of your choice, adding the following:

lazy val myFirstSetting = settingKey[Seq[String]]("Here is some documentation explaining myFirstSetting")
myFirstSetting := Seq("Here is myFirstSetting!")

Here, we create our first setting expression.

The setting is a lazy val instead of a val in order to avoid initialisation order problems.

All setting keys are instances of SettingKey[T]. We’ve denoted our type T as Seq[String].

After declaring the type of our settingKey, the string in brackets is where we can add documentation about our setting key if we would like. Or we can leave this as an empty string if we prefer.

The next line assigns the value "Here is myFirstSetting!" to myFirstSetting.

Let’s save this change to our build.sbt file.

From within our sbtSettings directory, we can start sbt, by typing sbt and at the sbt interactive console run show myFirstSetting. We should see the following:

sbt
> myFirstSetting
[info] * Here is myFirstSetting!

To see the documentation for our setting, type inspect myFirstSetting within the sbt interactive console.

sbt
> inspect myFirstSetting
[info] Setting: scala.collection.Seq[java.lang.String] = List(Here is myFirstSetting!)
[info] Description:
[info] 	Here is some documentation explaining myFirstSetting

Great! We’ve created our first sbt setting 🎉

Now you understand what sbt settings are, common setting keys, why they exist and how to create a simple one of your own.

To learn more, please check out the amazing sbt documentation.

Thank you!

If you don’t understand anything I’ve written here, please let me know as it’s not a shortcoming of yours but rather of mine! Similarly, please get in touch with improvement suggestions. Thank you ❤️