avatar

Andres Jaimes

Creating an sbt project from scratch

By Andres Jaimes

- 3 minutes read - 539 words

Files and project structure

sbt projects use the same structure as Maven. Creating a project from scratch involve the following steps:

mkdir some-new-project
cd some-new-project
mkdir -p src/{main,test}/{resources,scala}
mkdir project

Create a new file called build.sbt and add the following contents:

name := "SomeNewProject"
version := "1.0"
scalaVersion := "2.13.5"

Our final folder structure has to look like this:

.
├── build.sbt
├── project
└── src
    ├── main
    │   ├── resources
    │   └── scala
    └── test
        ├── resources
        └── scala

Done. Go ahead and try sbt clean or sbt compile. We are ready to start adding code to our folders.

Useful sbt commands

The following are a list common sbt commands:

clean
Removes all generated files from the target directory.
compile
Compiles source code files that are in src/main/scala, src/main/java, and the root directory of the project.
~compile
Automatically recompiles source code files while you’re running SBT in interactive mode (i.e., while you’re at the SBT command prompt).
console
Compiles the source code files in the project, puts them on the classpath, and starts the Scala interpreter (REPL).
consoleQuick
Starts the Scala interpreter (REPL) with the project dependencies on the classpath.
doc
Generates API documentation from your Scala source code using scaladoc.
help
Issued by itself, the help command lists the common commands that are currently available. When given a command, help provides a description of that command.
package
Creates a JAR file (or WAR file for web projects) containing the files in src/main/scala, src/main/java, and resources in src/main/resources.
package-doc
Creates a JAR file containing API documentation generated from your Scala source code.
publish
Publishes your project to a remote repository. See Recipe 18.15, “Publishing Your Library”.
publishLocal
Publishes your project to a local Ivy repository.
run
Compiles your code, and runs the main class from your project, in the same JVM as SBT.
sbt test -error
Runs all tests in the project, and shows only the errors.
test
Compiles and runs all tests.
testQuick
Compiles and runs only the tests that failed the previous time you ran tests.
~testQuick
Automatically recompiles and runs only the tests that failed the previous time you ran tests.
test:console
Compiles the source code files in the project, puts them on the classpath, and starts the Scala interpreter (REPL) in “test” mode (so you can use ScalaTest, Specs2, ScalaCheck, etc.).
update
Updates external dependencies.

Adding local projects as dependencies

There are times when we want to add a work-in-progress local library to another project as a dependency. One way to do it is to package the library and publish it to the local maven repository. However, we can instead add a reference to the library in the main project’s build.sbt file. A big benefit of this approach is that sbt will look for changes and recompile our library automatically when needed.

A sample dependency called myLibrary has been added to the following snippet:

name := "mainproject"
version := "1.0"

lazy val myLibrary = ProjectRef(file("../my-library-root-foolder"), "my-library-project-name")
lazy val `mainproject` = (project in file(".")).enablePlugins(PlayScala).dependsOn(myLibrary)
  • ../my-library-root-foolder has to point to the directory that contains the dependency’s build.sbt file.
  • my-library-project-name is the dependecy’s name set in build.sbt.

References