Difference Between % and %% Symbols in build.sbt

1. Introduction

The Simple Build Tool (sbt) is one of the most popular build tools for Scala. However, the syntax of the build.sbt file may be a bit confusing for newcomers. In this tutorial, we’ll discuss the difference between % and %% symbols used in defining dependencies.

2. A Simple build.sbt File

Let’s start by looking at a simple build.sbt file:

name := "build_sample"

version := "0.1"

scalaVersion := "2.12.11"

This is a very simple project with no external dependencies. In the next sections, we’ll see how to add dependencies to our build and what the % and %% symbols mean when defining dependencies.

3. Adding External Dependencies

Let’s say we want to add akka-actors to the project. We would add a libraryDependency statement:

libraryDependencies += "com.typesafe.akka" %% "akka-actor" % "2.6.6"

The dependency has three parts — groupId, artifactId, and version. These parts are separated by one or two percent (%) symbols. Let’s take a look at the % and %% symbols and why we use them.

3.1. Using Scala Library Dependencies

Unlike Java, Scala code is not compatible between different versions. For instance, we can’t use a Scala 2.12 library in a Scala 2.13 project. As a result, we need to be careful with specifying Scala versions of each library. However, if we use a double percent symbol (%%), sbt will resolve the relevant Scala version for us.

The sbt uses the project’s Scala version to resolve the library version. Additionally, this will help in easily upgrading the project to the latest Scala version. Therefore, we don’t need to worry about the library versions.

If we need to use a specific Scala version, we can use % to resolve the dependencies. In such a case, sbt will not resolve the Scala version of the library. We should provide the correct Scala version as part of the artifactId by using an underscore:

libraryDependencies += "com.typesafe.akka" % "akka-actor_2.12" % "2.6.5"

The artifactId has now become akka-actors_2.12.

If we don’t add the Scala version number to the artifactId, we’ll receive an error upon sbt refresh:

[error] (update) sbt.librarymanagement.ResolveException: Error downloading com.typesafe.akka:akka-actor:2.6.5
[error] not found: /home/administrator/.ivy2/local/com.typesafe.akka/akka-actor/2.6.5/ivys/ivy.xml
[error] not found: https://repo1.maven.org/maven2/com/typesafe/akka/akka-actor/2.6.5/akka-actor-2.6.5.pom
[error] (ssExtractDependencies) sbt.librarymanagement.ResolveException: Error downloading com.typesafe.akka:akka-actor:2.6.5

3.2. Using Java Library Dependencies

If we need to add a Java dependency as part of the project, we should always use a single percent(%) symbol.

Let’s see how to add the joda-time Java library as a dependency:

libraryDependencies += "joda-time" % "joda-time" % "2.10.6"

4. Conclusion

In this article, we’ve seen the difference between % and %% symbols in sbt.

Simply put, as a rule of thumb, %% should be used with all Scala libraries.