1. Introduction
SBT is the most popular build tool in the Scala ecosystem. It provides a lot of flexibility to configure the build to the user’s needs.
It also allows setting up some configurations at the user level, for all the projects. In this short tutorial, let’s look at the global configurations in more detail.
2. Why Global Configurations?
Generally, we provide the build configurations in the .sbt files within the project. That way, anyone cloning the repository will be able to build the project in the exact same way.
However, in some cases, it’s beneficial to have settings at the system level instead of the project. Here are some scenarios where global configurations become more useful:
- avoid saving credentials in the Git repository
- customization as per user affinity
- ability to share configurations across teams and projects
3. Global Configuration Usages
There are mainly three scenarios for global configuration usage. Let’s look at them in detail.
3.1. Global Settings and Tasks
We can add settings, tasks, and configurations globally by creating a .sbt file and placing it under the corresponding sbt version within the .sbt directory. Generally, the .sbt directory is available in the home directory of the user.
For sbt version 1.0 and above, the location is $HOME/.sbt/1.0. For the older versions, the path is $HOME/.sbt/0.13.
Now, we can create a file with .sbt extension, for example global.sbt. Next, let’s add some code to customize the sbt prompt:
shellPrompt := { state =>
s"\033[1;33m\033[43m[sbt ${name.value}]\033[0m >> "
}
Finally, we can start the sbt session within any of our projects. As a result of the global settings, here’s how the sbt shell now looks like:
More details about colors and formatting are available here.
3.2. Global Plugins
One of the most important features of sbt is the ability to extend the features using plugins. Normally, we add the plugins in plugins.sbt file within the project directory of our sbt module. However, we can also add plugins globally instead of at the project level.
We can look at it with an example. For this case, let’s use the sbt-prompt plugin to customize our shell prompt.
First, we need to create a file with the .sbt extension within $HOME/.sbt/1.0/plugins directory. We can then add the dependency for the plugin in that file:
addSbtPlugin("com.scalapenos" % "sbt-prompt" % "1.0.2")
Whenever we start the sbt session next, it uses the default theme from sbt-prompt for the shell. We should remember to remove the configuration for the shell prompt from the previous section, as otherwise, that takes higher preference over the plugin.
Additionally, we can also use other available themes by adding the configuration in the global configuration file at the path $HOME/.sbt/1.0:
import com.scalapenos.sbt.prompt.SbtPrompt.autoImport._
promptTheme := com.scalapenos.sbt.prompt.PromptThemes.ScalapenosTheme
After adding this, the new theme is applied to the sbt shell prompt:
Since it uses custom fonts, the prompt might not look exactly the same if the relevant fonts aren’t available in the system.
3.3. Shareable Configurations
Another use case for global configuration is to keep credentials for services such as Artifactory. We can keep the credentials in the global configuration instead of saving them within the repository. Hence, this ensures that the credentials aren’t exposed.
4. Overriding Global Configurations
We can override the global configurations with project-specific values. In the previous section, we used the sbt-prompt plugin to apply the formatting globally. Now, within one of our projects, we can add another configuration for the shell prompt:
shellPrompt := { state =>
"[sbt (%s)====>] ".format(Project.extract(state).currentProject.id)
}
Finally, let’s start the sbt session within this module. We can see that the shell prompt is changed to the new one only for this project:
5. Conclusion
In this short article, we looked at the global configurations in SBT.
As always, the sample settings and configurations we used in this tutorial are available over on GitHub.