SBT
Importing an sbt project
- Click Import Project or Open on the welcome screen.
- In the dialog that opens, select a directory that contains your sbt project or simply
build.sbt
. Click OK. - Follow the steps suggested in the Import Project wizard.
You can use the suggested default settings since they are enough to successfully import your project.
We recommend that you enable the Use sbt shell for build and import (requires sbt 0.13.5+) option when you use code generation or other features that modify the build process in sbt. If your sbt project is not in the IntelliJ IDEA project root directory, we suggest you skip this option.
You can also select the appropriate option for grouping modules in your project.
Ensuring sbt and Scala versions compatibility
Often you share your project across a team and need to use a specific version of sbt.
You can override the sbt version in your project's build.properties
file.
- Create or import your sbt project.
- In the Project tool window, in the source root directory locate the
build.properties
file and open it in the editor. - In the editor explicitly specify the version of sbt that you want to use in the project.
sbt.version=xxx
- Refresh your project. (Click the in the sbt projects tool window.)
Managing sbt projects
sbt project structure
When you create or import an sbt project, IntelliJ IDEA generates the following sbt structure:
- sbt project (proper build) which defines a project and contains
build.sbt
file, src, and target directories, modules; anything related to a regular project. - sbt build project which is defined in the project subdirectory. It contains additional code that is part of the build definition.
- The sbt projects tool window which contains sbt tasks, commands, and settings that you can execute.
When you work with sbt projects you use the build.sbt
file to make main changes to your project since IntelliJ IDEA considers an sbt configuration as a single source of truth.
To see what common tasks you can perform via build.sbt
, refer to the Commonly performed sbt tasks section.
Adding a library to the sbt project
You can add sbt dependencies via the build.sbt
file or you can use the import
statement in your .scala
file.
- Open a
.scala
file in the editor. - Specify a library you want to import.
- Put the cursor on the unresolved package and press Alt+Enter.
- From the list of available intention actions, select Add sbt dependency.
- Follow the steps suggested in the wizard that opens and click Finish.
- IntelliJ IDEA downloads the artifact, adds the dependency to the
build.sbt
file and to the sbt projects tool window.
Working with sbt shell
An sbt shell is embedded in the sbt project and is available on your project start. You can use the sbt shell for executing sbt commands and tasks, for running, and debugging your projects.
- To start the sbt shell, press Ctrl+Shift+S(for Windows) or Cmd+Shift+S (for Mac OS X). Alternatively, click on the toolbar located on the bottom of the screen.
- To use the sbt shell for build and import procedures, select the Use sbt shell for build and import (requires sbt 0.13.5+) option located in the sbt settings and perform steps described in the Run a Scala application using the sbt shell section. Note that sbt versions 0.13.16.+ / 1.0.3.+ are recommended.
- To use the sbt shell for debugging, refer to the debugging with sbt shell section.
- To run your tests from the sbt shell:
- Open a run/debug configuration ( ).
- Create a test configuration and select the use sbt option from the available settings.
Running sbt tasks
- You can run sbt tasks by selecting the one you need from the the sbt Tasks directory in the sbt projects tool window.
- You can manually enter your task (code completion is supported) in the sbt shell and run it directly from there.
- You can create a run configuration for a task. For example, you can create a custom task which is not part of the list of tasks located in the sbt projects tool window.
- Open (Shift+Alt+F10) a run configuration.
- Specify the run configuration settings and click OK. If you need, you can add another configuration or a task to execute before running your configuration. Click the icon in the Before Launch section and from the list that opens select what you need to execute.
IntelliJ IDEA displays results in the sbt shell window.
Working with sbt settings
To access sbt settings, click in the sbt projects tool window.
You can use sbt settings for the following notable actions:
- If you want sbt automatically refresh your project every time you make changes to
build.sbt
, select Use auto-import. - To delegate running builds to sbt, select Use sbt shell for build and import.
- To debug your code via the sbt shell, select Enable debugging for sbt shell option that enables a debug button () in the sbt shell tool window. To start the debugging session, simply click this button. For more information on debugging, see debugging with sbt.
- To change the .ivy cache location in your project or set other sbt properties, use the VM parameters field.
Commonly performed sbt tasks
Linking an external sbt project
You can link an external sbt project to the sbt project that you already have.
- Open your
build.sbt
. - Specify the following code: where
val localDep = RootProject(file("/path/to/project"))
localDep
in this case is a project that is located somewhere on the file system and will be imported as a module. - Refresh your project. (Click the in the sbt projects tool window.)
IntelliJ IDEA displays the added project in the Project tool window as well as in the sbt projects tool window.
Working with an sbt multi-module project
You can add a sub project or a module that would depend on your main sbt project using the build.sbt
file.
- Open
build.sbt
in the editor. - Specify, for example: where "sampleModule" is a sub project that you want to add. You can specify more than one sub project.
lazy val sampleModule = (project in file("sampleModule"))
- Refresh your project. (Click the in the sbt projects tool window.)
IntelliJ IDEA generates a sub project directory with the appropriate information and displays it in both Project and sbt projects tool windows.
If you want the sub projects to automatically update when you change the version of Scala, specify commonSettings
and settings
method call for each sub project.
- Open
build.sbt
. - Specify, for example, the following code:
lazy val commonSettings = Seq( organization := "com.example", version := "0.1.0-SNAPSHOT", scalaVersion := "2.12.3" ) lazy val moduleSample = (project in file("moduleSample")) .settings( commonSettings )
The appropriate Scala version is added to the sub project's directory in the Project tool window and also to the sbt projects tool window as a dependency in the sub project.
Working with dependencies in sbt projects
IntelliJ IDEA lets you use external dependencies in your sbt project.
You can use both managed dependencies and unmanaged dependencies:
- Managed dependencies are the ones that are added through
build.sbt
and managed by sbt. - The unmanaged dependencies are the ones that you add to the
lib
directory in your project and manage manually.
We recommend that you use build.sbt
for configuring all of the dependencies to ensure portability of the project.
- Open
build.sbt
in the editor. - Specify your dependency which have the following syntax:
You can also declare several dependencies:libraryDependencies += groupID % artifactID % revision
You can also configure dependencies externally in the Maven POM file or Ivy configuration file and let sbt use those files. For more information, please refer to the sbt Library Management page.libraryDependencies ++= Seq( groupID % artifactID % revision, groupID % otherID % otherRevision )