sbt is a build tool used by many Scala projects. Developers using sbt will rarely need to know more than the basic commands like
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
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 (
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:
inside our directory, let’s create a new file and name it
cd sbtSettings touch build.sbt
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
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
Let’s save this change to our
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.
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 ❤️