How to Use the Command sbt (with examples)

Scala Build Tool (sbt) is a popular build tool for Scala and Java projects. It provides a simple and efficient way to build, test, and run projects. This article will demonstrate various use cases of the sbt command.

Use case 1: Start a REPL (interactive shell)

Code:

sbt

Motivation: Starting a REPL allows developers to interactively run and test code snippets. It is useful for experimenting with small code segments or trying out new features or libraries.

Explanation: When the sbt command is executed without any arguments, it starts the sbt interactive shell or REPL. This shell provides a command-line interface where users can enter commands, execute tasks, and interact with the project.

Example output:

[info] Loading project definition from /path/to/project
[info] Set current project to project-name
[info] sbt server started at local://localhost:38670
sbt:project-name>

Use case 2: Create a new Scala project from an existing Giter8 template hosted on GitHub

Code:

sbt new scala/hello-world.g8

Motivation: Creating a new project from a template provides a quick way to bootstrap a project with predefined structure and settings. Giter8 is a template generation tool that supports various project templates.

Explanation: The new command in sbt is used to create a new project from a Giter8 template. When provided with the scala/hello-world.g8 argument, sbt fetches the specified template from GitHub and generates a new project with the provided template.

Example output:

[info] Set current project to hello-world (in build ...)
[info] Running giter8.TwirlHelper
name [Hello World]: MyProject
organization [com.example]: com.mycompany
[info] Run completed in 354 milliseconds.
[info] Generated new app and test for MyProject, happy coding.
[success] Total time: 6 s, completed ...

Use case 3: Compile and run all tests

Code:

sbt test

Motivation: Running tests ensures the correctness and reliability of the project’s codebase. It helps identify any issues or bugs early in the development cycle.

Explanation: The test command in sbt compiles and runs all tests present in the project. It executes all test suites and reports the test results.

Example output:

[info] Compiling 10 Scala sources and 5 Java sources to /path/to/target/scala-2.13/classes ...
[info] Compiling 5 Scala sources and 2 Java sources to /path/to/target/scala-2.13/test-classes ...
[info] MySpec:
[info] The MyClass
[info] - should return true if the condition is met
[info] Run completed in 778 milliseconds.
[info] Total number of tests run: 1
[info] Suites: completed 1, aborted 0
[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0
[info] All tests passed.
[success] Total time: 17 s, completed ...

Use case 4: Delete all generated files in the target directory

Code:

sbt clean

Motivation: Cleaning the project directory is useful when there are leftover artifacts, temporary files, or build outputs that need to be removed. It provides a clean slate for subsequent builds.

Explanation: The clean command in sbt removes all generated files and directories in the target directory. This includes compiled classes, generated resources, and other build artifacts.

Example output:

[info] Deleting /path/to/target ...
[success] Total time: 1 s, completed ...

Use case 5: Compile the main sources in src/main/scala and src/main/java directories

Code:

sbt compile

Motivation: Compiling the main sources ensures that the project’s code is error-free and ready to be packaged or executed. It checks for any compilation errors and produces bytecode from the source code.

Explanation: The compile command in sbt compiles the main sources in the src/main/scala and src/main/java directories. It checks for any source code changes and compiles only the modified files or the dependencies affected by the changes.

Example output:

[info] Compiling 20 Scala sources and 10 Java sources to /path/to/target/scala-2.13/classes ...
[success] Total time: 12 s, completed ...

Use case 6: Use the specified version of sbt

Code:

sbt -sbt-version 1.5.5

Motivation: Specifying the version of sbt allows for consistency across different environments and ensures compatibility with specific features or plugins.

Explanation: The -sbt-version argument allows users to specify the desired version of sbt to use. In the example, 1.5.5 is provided as the version number, indicating that the project should be built using sbt version 1.5.5.

Example output:

[info] Loading project definition from /path/to/project
[info] Set current project to project-name (in build ...)
[info] sbt server started at local://localhost:49392
sbt:project-name> 

Use case 7: Use a specific jar file as the sbt launcher

Code:

sbt -sbt-jar path/to/sbt-launch.jar

Motivation: Using a specific sbt launcher allows for custom versions or configurations to be used. This can be useful for testing new features, implementing customizations, or working with non-standard setups.

Explanation: The -sbt-jar argument specifies the path to the sbt launcher jar file to be used. By providing a custom jar file, users can override the default sbt launcher and use their own version or a modified version of sbt.

Example output:

[info] Loading project definition from /path/to/project
[info] Set current project to project-name (in build ...)
[info] sbt server started at local://localhost:54628
sbt:project-name> 

Use case 8: List all sbt options

Code:

sbt -h

Motivation: Finding out the available options helps users customize the sbt build process, learn about additional functionalities, or identify potential troubleshooting options.

Explanation: The -h argument displays a list of all available options for the sbt command. It provides an overview of the command-line arguments, environment variables, and system properties that can be used to configure sbt’s behavior.

Example output:

> sbt -h
Build tool for Scala projects.

Usage:
  sbt [options] [<task>]

[...]

Conclusion:

In this article, we have explored several use cases of the sbt command. From starting a REPL to creating projects from templates, compiling code, running tests, and customizing sbt versions and configurations - sbt provides a flexible and powerful toolset for Scala and Java projects. Understanding these various use cases can help developers leverage sbt effectively in their development workflows.