SBT

Creating an sbt project

1. Launch the New Project wizard and follow the steps suggested in the wizard.
2. Select Scala and sbt.
3. Specify your project's name, location, JDK along with sbt and Scala versions. The sbt and Scala versions are fetched automatically.

Importing an sbt project

1. Click Import Project on the welcome screen or select File | New | Project from Existing Sources from the main menu.
2. In the dialog that opens, select a directory that contains your sbt project or simply build.sbt. Click OK.
3. Follow the steps suggested in the Import Project wizard.
4. 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 to skip this option.

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 define a custom sbt launcher to override the default sbt version:
  1. If you have an open sbt project, in the sbt projects tool window, click the icon.
  2. In the dialog that opens, in the Launch (sbt-launch.jar) section, select the Custom option.
  3. In the Custom field, enter the location of your sbt launcher and click OK.

  Alternatively, you can specify a custom launcher when you import an sbt project.

• You can override the sbt version in your project's build.properties file.
  1. Create or import your sbt project.
  2. In the Project tool window, in the source root directory locate the build.properties file and open it in the editor.
  3. In the editor explicitly specify the version of sbt that you want to use in the project.

     sbt.version=xxx

     Note that newer sbt versions will create the build.properties file automatically if it doesn't exist.

  4. 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.
• sbt projects tool window which contains sbt tasks, commands, and settings that you can execute.

For more information on sbt project structure, see the related sbt documentation.

Linking an external sbt project

You can link an external sbt project to the sbt project that you already have.

1. Open your build.sbt.
2. Specify the following code:

   val localDep = RootProject(file("/path/to/project"))

   where localDep in this case is a project that is located somewhere on the file system and will be imported as a module.
3. 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.

1. Open build.sbt in the editor.
2. Specify, for example:

   lazy val sampleModule = (project in file("sampleModule"))

   where "sampleModule" is a sub project that you want to add. You can specify more than one sub project.
3. 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.

1. Open build.sbt.
2. 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.

1. Open build.sbt in the editor.
2. Specify your dependency which have the following syntax:
   
   

   libraryDependencies += groupID % artifactID % revision

   You can also declare several dependencies:

   libraryDependencies ++= Seq(
   groupID % artifactID % revision,
   groupID % otherID % otherRevision
   )

   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.

   By default, sbt uses standard Maven2 repository to retrieve dependencies. The repository can locate most libraries when you specify a libraryDependencies line in the build.sbt file. You don't need to specify the location of the library. However, when a library is not in a standard repository, you can tell sbt where to search by adding a resolver.

Alternatively, you can let sbt import a library that you would add via import statement.

• Open build.sbt in the editor.
• Specify a library you want to import.

Working with sbt shell

An sbt shell is the embedded version of sbt command that you usually run on the command line. The sbt shell is part of an sbt project so you don't need to perform any additional installation.

• To open the sbt shell, click the on the toolbar located in the sbt projects tool window.
• To use the sbt shell for build and import procedures, you need to specify 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.
• You can use the sbt shell for debugging as described in the debugging with sbt shell section.
• You can run program and tests from the sbt shell. You can use the use sbt option test run configuration. You can also use test or test/Only command.

Running sbt tasks

You execute sbt commands and settings the same way as you would execute sbt tasks.

Running an sbt task via the sbt projects tool window

You can run sbt tasks by selecting the one you need from the sbt projects tool window.

1. In your sbt project, in the sbt projects tool window, click a project or module for which you want to execute a task.
2. In the list that opens, click sbt Tasks directory.
3. From the list that opens, double-click the appropriate task to run. Alternatively, right-click the task and from the context menu, click Run.
4. If you want to perform an action other than execution, right-click the task and from the context menu, click the appropriate action.
5. Check the results in the sbt Shell window.

Running an sbt task via the sbt shell

You can enter and run your task directly in the sbt Shell.

1. In the sbt projects tool window, click to launch the sbt shell.
2. In the sbt Shell window, start typing a name of the task you need to run, IntelliJ IDEA supports code completion.
3. Press ⏎⏎⏎⏎⏎.

Creating a run configuration for an sbt task

You can create a run configuration for an sbt 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.

1. On the main menu, select Run | Edit Configurations.
2. In the dialog that opens, click the icon to open a list of new configurations.
3. In the list that opens, locate and select sbt Task.
4. On the right side of the sbt task configuration page, specify a name of your configuration, tasks that you want to include for this configuration and other related options.
   
   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.
5. Click OK.
6. Run your configuration and check the results in the Run tool 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(requires sbt 0.13.5+).
• 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.