Defaults API

Default implementations and build settings provided by sbt

Defaults API

The Defaults object (defined in sbt.Defaults) provides default implementations for common build settings and tasks. It extends BuildCommon and contains the core configuration that makes sbt work out of the box.

Core Build Settings

buildCore

lazy val buildCore: Seq[Setting[?]]

Core settings required for every sbt build.

buildCore · Seq[Setting[?]]

Combines thisBuildCore and globalCore to provide essential build infrastructure.

Components:

• Build-level settings (thisBuildCore)
• Global settings (globalCore)

Location: Defaults.scala:144

globalCore

lazy val globalCore: Seq[Setting[?]]

Global default settings applied to all projects.

globalCore · Seq[Setting[?]]

Includes file filters, test tasks, Ivy configuration, JVM settings, watch settings, and sbt core functionality.

Includes:

• Default file filters (excludeFilter, includeFilter)
• Test task defaults
• File input/output configuration
• Watch service settings
• Global Ivy and JVM settings

Location: Defaults.scala:151

JVM Configuration

globalJvmCore

lazy val globalJvmCore: Seq[Setting[?]]

JVM-specific global settings.

globalJvmCore · Seq[Setting[?]]

Configures Scala instances, compiler cache, classpath options, and JVM-related defaults.

Key Settings:

• compilerCache - Compiler instance cache
• sourcesInBase - Include sources from base directory
• autoScalaLibrary - Automatically add scala-library dependency
• managedScalaInstance - Use managed Scala instance
• autoCompilerPlugins - Automatically detect compiler plugins
• scalaHome - Local Scala installation (default: None)
• javaHome - Java installation for compilation/forking
• javaOptions - JVM options for forked processes
• sbtPlugin - Enable sbt plugin mode
• crossPaths - Enable cross-version paths

Location: Defaults.scala:172

Dependency Management

globalIvyCore

lazy val globalIvyCore: Seq[Setting[?]]

Ivy and dependency resolution settings.

globalIvyCore · Seq[Setting[?]]

Configures dependency resolution, repositories, versioning, and publishing defaults.

Key Settings:

• internalConfigurationMap - Configuration mapping
• credentials - Publishing credentials
• exportJars - Export JARs instead of classes
• scalaOrganization - Scala artifact organization
• sbtResolver - Resolver for sbt artifacts
• version - Project version (default: “0.1.0-SNAPSHOT”)
• checksums - Checksum algorithms
• conflictManager - Dependency conflict resolution
• csrCacheDirectory - Coursier cache location
• csrReconciliations - Version reconciliation strategies

Location: Defaults.scala:249

Path Configurations

paths

def paths: Seq[Setting[?]]

Default directory structure settings.

paths · Seq[Setting[?]]

Defines standard project directories: base, target, sources, and resources.

Configured Paths:

• baseDirectory - Project root directory
• target - Build output directory
• sourceDirectory - Source root (src)
• sourceManaged - Generated sources
• resourceManaged - Generated resources

Location: Defaults.scala:549

configPaths

lazy val configPaths: Seq[Setting[?]]

Configuration-specific path settings.

configPaths · Seq[Setting[?]]

Combines source, resource, and output paths for configurations like Compile and Test.

Components:

• sourceConfigPaths - Source directories
• resourceConfigPaths - Resource directories
• outputConfigPaths - Output directories

Location: Defaults.scala:567

sourceConfigPaths

lazy val sourceConfigPaths: Seq[Setting[?]]

Source directory configuration.

sourceConfigPaths · Seq[Setting[?]]

Defines managed and unmanaged source directories with cross-version support.

Key Settings:

• sourceDirectory - src/main or src/test
• scalaSource - Scala source directory
• javaSource - Java source directory
• unmanagedSourceDirectories - Manual source directories
• managedSourceDirectories - Generated source directories
• sourceGenerators - Tasks that generate sources

Location: Defaults.scala:568

Compilation Settings

compileBase

def compileBase: Seq[Setting[?]]

Core compilation configuration.

compileBase · Seq[Setting[?]]

Sets up Scala instances, compiler bridges, classpath options, and console configuration.

Key Components:

• Scala instance configuration
• Compiler bridge setup
• Cross-version settings
• Console and REPL configuration
• Classpath options

Location: Defaults.scala:679

configTasks

lazy val configTasks: Seq[Setting[?]]

Configuration-level task definitions.

configTasks · Seq[Setting[?]]

Defines compile, run, test, and documentation tasks for a configuration.

Key Tasks:

• compile - Incremental compilation
• compileIncremental - Internal incremental compile
• copyResources - Resource copying
• console - Scala REPL
• run / runMain - Application execution
• clean - Artifact cleanup
• doc - API documentation generation

Location: Defaults.scala:940

compileAnalysisSettings

lazy val compileAnalysisSettings: Seq[Setting[?]]

Zinc incremental compilation analysis configuration.

compileAnalysisSettings · Seq[Setting[?]]

Configures analysis storage, compiler setup, and incremental compilation.

Includes:

• compileAnalysisFile - Analysis storage location
• compileIncSetup - Incremental compiler setup
• incOptions - Incremental compilation options

Testing Configuration

testTasks

lazy val testTasks: Seq[Setting[?]]

Test execution task definitions.

testTasks · Seq[Setting[?]]

Configures test discovery, execution, filtering, and reporting.

Key Tasks:

• test - Run tests incrementally
• testOnly - Run specific tests
• testQuick - Run failed/affected tests
• testFull - Run all tests
• definedTests - Discovered test classes
• loadedTestFrameworks - Available test frameworks
• executeTests - Test execution engine

Location: Defaults.scala:1165

testDefaults

private def testDefaults: Seq[Setting[?]]

Global test framework defaults.

testDefaults · Seq[Setting[?]]

Default test frameworks, listeners, options, and result logging.

Defaults:

• testFrameworks - All standard frameworks (ScalaTest, specs2, JUnit, etc.)
• testListeners - Empty by default
• testOptions - Empty by default
• testResultLogger - Default test result logger

Location: Defaults.scala:1152

Helper Functions

makeCrossSources

def makeCrossSources(
    scalaSrcDir: File,
    javaSrcDir: File,
    sv: String,
    epochVersion: String,
    cross: Boolean
): Seq[File]

Generates cross-versioned source directories.

scalaSrcDir · File · required

Base Scala source directory

javaSrcDir · File · required

Base Java source directory

sv · String · required

Scala version (e.g., “2.13”, “3”)

epochVersion · String · required

Epoch version (e.g., “2” for Scala 2, “3” for Scala 3)

cross · Boolean · required

Enable cross-version source directories

result · Seq[File]

List of source directories including cross-version variants

Returns: When cross is true:

• Base Scala directory
• scala-<sv> directory (e.g., scala-2.13)
• scala-<epochVersion> directory (e.g., scala-2)
• Java directory

Location: Defaults.scala:835

makeCrossTarget

def makeCrossTarget(
    t: File,
    scalaVersion: String,
    scalaBinaryVersion: String,
    sbtv: String,
    plugin: Boolean,
    cross: Boolean
): File

Generates cross-versioned target directory.

t · File · required

Base target directory

scalaVersion · String · required

Full Scala version

scalaBinaryVersion · String · required

Scala binary version

sbtv · String · required

sbt version

plugin · Boolean · required

Is this an sbt plugin?

cross · Boolean · required

Enable cross-building

result · File

Target directory path with version suffixes

Returns:

• For Scala 3: target/scala-<fullVersion>/
• For Scala 2: target/scala-<binaryVersion>/
• For plugins: Additional sbt-<version>/ suffix

Location: Defaults.scala:876

generate

def generate(generators: SettingKey[Seq[Task[Seq[File]]]]): Initialize[Task[Seq[File]]]

Runs all generator tasks and collects results.

generators · SettingKey[Seq[Task[Seq[File]]]] · required

Setting key containing generator tasks (e.g., sourceGenerators, resourceGenerators)

result · Initialize[Task[Seq[File]]]

Flattened list of all generated files

Location: Defaults.scala:1133

Project-Level Settings

projectCore

def projectCore: Seq[Setting[?]]

Core project-level settings.

projectCore · Seq[Setting[?]]

Basic project configuration including name and logging.

Settings:

• name - Derived from project ID
• logManager - Logging manager setup
• onLoadMessage - Project load notification

Location: Defaults.scala:539

projectTasks

lazy val projectTasks: Seq[Setting[?]]

Project-level task definitions.

projectTasks · Seq[Setting[?]]

Tasks that operate on the entire project.

Tasks:

• cleanFiles - Files to delete on clean
• clean - Clean task implementation
• transitiveDynamicInputs - Watch dependency tracking

Location: Defaults.scala:1124

Usage Example

import sbt._
import sbt.Keys._
import Defaults._

lazy val myProject = (project in file("."))
  .settings(
    name := "my-project",
    scalaVersion := "3.3.1",
    // Defaults.configPaths is automatically applied
    // Defaults.compileBase is automatically applied
    // Defaults.testTasks is automatically applied
  )

Most Defaults settings are applied automatically by sbt’s plugin system and don’t need explicit configuration.