Project API

Project definition and build structure API in sbt

Project API

The Project object and related types (defined in sbt.Project and sbt.ProjectExtra) provide the API for defining projects, managing build structure, and navigating project references.

Project Definition

Project Constructor

def apply(id: String, base: File): Project

Creates a new project definition.

id · String · required

Unique identifier for the project within the build

base · File · required

Base directory for the project (typically a subdirectory of the build root)

result · Project

A new project that can be configured with settings, dependencies, and plugins

Example:

lazy val core = project
  .in(file("core"))
  .settings(
    name := "my-core"
  )

Project Configuration Methods

settings

def settings(ss: Def.SettingsDefinition*): Project

Appends settings to the project.

ss · Def.SettingsDefinition* · required

Variable number of setting definitions to add

result · Project

The project with additional settings

Example:

project
  .settings(
    name := "my-project",
    version := "1.0.0",
    scalaVersion := "3.3.1"
  )

dependsOn

def dependsOn(deps: ClasspathDep[ProjectReference]*): Project

Adds classpath dependencies on internal or external projects.

deps · ClasspathDep[ProjectReference]* · required

Project references with optional configuration mapping

result · Project

The project with inter-project dependencies

Example:

lazy val app = project
  .dependsOn(core)
  .dependsOn(util % "compile->compile;test->test")

Location: Conceptual location in Project trait

aggregate

def aggregate(refs: ProjectReference*): Project

Adds projects to be aggregated.

refs · ProjectReference* · required

Projects to aggregate (tasks will cascade to aggregated projects)

result · Project

The project that aggregates the specified projects

Description: When a user requests a task on this project, the task also runs in aggregated projects.

Example:

lazy val root = (project in file("."))
  .aggregate(core, util, app)

configs

def configs(cs: Configuration*): Project

Adds configurations to the project.

cs · Configuration* · required

Custom configurations to add

result · Project

The project with additional configurations

Example:

val IntegrationTest = config("it") extend Test

project
  .configs(IntegrationTest)
  .settings(
    inConfig(IntegrationTest)(Defaults.testSettings)
  )

overrideConfigs

def overrideConfigs(cs: Configuration*): Project

Adds or replaces configurations.

cs · Configuration* · required

Configurations that will replace existing ones with the same name

result · Project

The project with updated configurations

Location: ProjectExtra.scala:163

enablePlugins

def enablePlugins(ns: Plugins*): Project

Enables AutoPlugins for the project.

ns · Plugins* · required

AutoPlugin instances to enable

result · Project

The project with specified plugins enabled

Example:

project
  .enablePlugins(ScalaJSPlugin)

disablePlugins

def disablePlugins(ps: AutoPlugin*): Project

Disables AutoPlugins for the project.

ps · AutoPlugin* · required

AutoPlugin instances to disable

result · Project

The project with specified plugins disabled

Example:

project
  .disablePlugins(AssemblyPlugin)

Build Structure

structure

def structure(state: State): BuildStructure

Extracts the build structure from state.

state · State · required

Current build state

result · BuildStructure

Complete build structure including all projects, settings, and indexes

Location: ProjectExtra.scala:270

session

def session(state: State): SessionSettings

Extracts the session settings from state.

state · State · required

Current build state

result · SessionSettings

Current session configuration including current project and session settings

Location: ProjectExtra.scala:273

extract

def extract(state: State): Extracted

Extracts build information from state.

state · State · required

Current build state

result · Extracted

Extracted build data containing structure, session, and current reference

Description: Provides convenient access to the build structure, session settings, and current project.

Example:

val extracted = Project.extract(state)
val currentProject = extracted.currentRef
val buildStruct = extracted.structure

Location: ProjectExtra.scala:291

Project References

ProjectRef

final class ProjectRef(val build: URI, val project: String) extends ProjectReference

References a specific project in a specific build.

build · URI · required

URI of the build containing the project

project · String · required

Project identifier within that build

Example:

val coreRef = ProjectRef(file("../core").toURI, "core")

LocalProject

final case class LocalProject(project: String) extends ProjectReference

References a project in the current build by ID.

project · String · required

Project identifier in the current build

Example:

lazy val app = project
  .dependsOn(LocalProject("core"))

RootProject

final case class RootProject(build: URI) extends ProjectReference

References the root project of a build.

build · URI · required

URI of the build

Build Navigation

current

def current(state: State): ProjectRef

Gets the current project reference.

state · State · required

Build state

result · ProjectRef

Reference to the currently selected project

Location: ProjectExtra.scala:351

getProject

def getProject(
    ref: ProjectRef,
    structure: BuildStructure
): Option[ResolvedProject]

Retrieves a project definition.

ref · ProjectRef · required

Project reference

structure · BuildStructure · required

Build structure

result · Option[ResolvedProject]

The resolved project if it exists

Location: ProjectExtra.scala:306

Scope Helpers

inConfig

def inConfig(conf: Configuration)(ss: Seq[Setting[?]]): Seq[Setting[?]]

Scopes settings to a specific configuration.

conf · Configuration · required

Configuration scope (Compile, Test, Runtime, etc.)

ss · Seq[Setting[?]] · required

Settings to scope

result · Seq[Setting[?]]

Settings scoped to the configuration

Example:

lazy val root = project
  .settings(
    inConfig(Test)(
      Seq(
        fork := true,
        javaOptions += "-Xmx2G"
      )
    )
  )

Location: ProjectExtra.scala:158

Display and Debugging

showContextKey

def showContextKey(state: State): Show[ScopedKey[?]]

Creates a display formatter for scoped keys.

state · State · required

Current state

result · Show[ScopedKey[?]]

Formatter that shows keys relative to current context

Location: ProjectExtra.scala:199

details

def details(
    structure: BuildStructure,
    actual: Boolean,
    key: ScopedKey[?]
)(using display: Show[ScopedKey[?]]): String

Generates detailed information about a key.

structure · BuildStructure · required

Build structure

actual · Boolean · required

Show actual or declared dependencies

key · ScopedKey[?] · required

Key to inspect

result · String

Formatted details including description, dependencies, and delegates

Location: ProjectExtra.scala:434

Classpath Dependencies

ClasspathDependency

final case class ClasspathDependency(
    project: ProjectReference,
    configuration: Option[String]
) extends ClasspathDep[ProjectReference]

Represents a classpath dependency with configuration mapping.

project · ProjectReference · required

Referenced project

configuration · Option[String]

Configuration mapping (e.g., “compile->compile;test->test”)

Example:

// Simple dependency (defaults to compile->compile)
project.dependsOn(core)

// With configuration mapping
project.dependsOn(core % "compile->compile;test->test")

// Test-only dependency  
project.dependsOn(testUtils % "test->compile")

% Operator

extension (p: ProjectReference)
  def %(conf: Configuration): ClasspathDependency
  def %(conf: String): ClasspathDependency

Creates a classpath dependency with configuration mapping.

p · ProjectReference · required

Project reference

conf · Configuration | String · required

Configuration or configuration mapping string

result · ClasspathDependency

Configured classpath dependency

Example:

core % Test
core % "test->compile"

Location: ProjectExtra.scala:689

Full Example

import sbt._
import sbt.Keys._

lazy val commonSettings = Seq(
  organization := "com.example",
  version := "1.0.0",
  scalaVersion := "3.3.1"
)

lazy val core = (project in file("core"))
  .settings(
    commonSettings,
    name := "my-core",
    libraryDependencies ++= Seq(
      "org.typelevel" %% "cats-core" % "2.10.0"
    )
  )

lazy val util = (project in file("util"))
  .settings(
    commonSettings,
    name := "my-util"
  )
  .dependsOn(core)

lazy val app = (project in file("app"))
  .settings(
    commonSettings,
    name := "my-app"
  )
  .dependsOn(
    core % "compile->compile",
    util % "compile->compile;test->test"
  )

lazy val root = (project in file("."))
  .settings(
    commonSettings,
    name := "my-project"
  )
  .aggregate(core, util, app)