sbt inspect

概要

sbt inspect [subproject / ] [ config / ] task
sbt inspect actual [subproject / ] [ config / ] task
sbt inspect tree [subproject / ] [ config / ] task

描述

inspect 命令提供检查任务和设置图的方式。例如，可用于确定应修改哪个设置以影响其他任务。

值、描述和提供来源

inspect 提供的第一条信息是任务的类型或设置的值和类型。

例如：

$ sbt inspect libraryDependencies
[info] Setting: interface scala.collection.immutable.Seq =
  List(org.scala-lang:scala3-library:3.7.2,
       org.typelevel:toolkit:0.1.29,
       org.typelevel:toolkit-test:0.1.29:test)
[info] Description:
[info]  Declares managed dependencies.
[info] Provided by:
[info]  ProjectRef(uri("file:/tmp/aaa/"), "aaa") / libraryDependencies
....

输出的下一部分标为 "Provided by"。显示定义该设置的实际作用域。

这表明 libraryDependencies 已在当前项目（ProjectRef(uri("file:/tmp/aaa/"), "aaa")）上定义。

设置依赖关系

正向依赖显示用于定义设置（或任务）的其他设置（或任务）。反向依赖则相反，显示哪些使用了给定设置。inspect 根据指定依赖或有效依赖提供此信息。指定依赖是设置直接指定的；有效设置是这些依赖解析后的结果。以下各节将更详细地说明这一区别。

指定设置依赖

例如，我们来看 console：

$ sbt inspect console
...
[info] Dependencies:
[info]  Compile / console / initialCommands
[info]  Compile / console / compilers
[info]  Compile / state
[info]  Compile / console / cleanupCommands
[info]  Compile / console / taskTemporaryDirectory
[info]  Compile / console / scalaInstance
[info]  Compile / console / scalacOptions
[info]  Compile / console / fullClasspath
[info]  Compile / fileConverter
[info]  Compile / console / streams

...

这显示 console 任务的输入。可见其 classpath 和选项来自 Compile / console / fullClasspath 和 Compile / console / scalacOptions。inspect 命令提供的信息有助于找到要修改的正确设置。键的约定（如 console 和 fullClasspath）是：Scala 标识符为驼峰式，字符串表示为小写并用连字符分隔。配置的 Scala 标识符为大写，以区别于 compile 和 test 等任务。例如，从前例可推断如何在 Scala 解释器启动时添加要运行的代码：

> set Compile / console / initialCommands := "import mypackage._"
> console
...
import mypackage._
...

inspect 显示 console 使用设置 Compile / console / initialCommands。将 initialCommands 字符串转换为 Scala 标识符即得 initialCommands。compile 表示用于主源。console / 表示该设置专用于 console。因此，我们可在 console 任务上设置初始命令而不影响 consoleQuick 任务。

有效设置依赖

inspect actual <scoped-key> 显示实际使用的依赖。这很有用，因为委托意味着依赖可能来自请求作用域之外。使用 inspect actual 可准确看到哪个作用域为设置提供值。将 inspect actual 与普通 inspect 结合，可看到影响设置的作用域范围。回到「指定设置依赖」中的示例：

$ sbt inspect actual console
...
[info] Dependencies:
[info]  Compile / console / streams
[info]  Global / taskTemporaryDirectory
[info]  scalaInstance
[info]  Compile / scalacOptions
[info]  Global / initialCommands
[info]  Global / cleanupCommands
[info]  Compile / fullClasspath
[info]  console / compilers
...

对于 initialCommands，可见其来自全局作用域（Global）。结合 inspect console 的相关输出：

Compile / console / initialCommands

可知可将 initialCommands 设置为与全局作用域一样通用、与当前项目的 console 任务作用域一样具体，或介于两者之间。这意味着例如可为整个项目设置 initialCommands，将影响 console：

> set initialCommands := "import mypackage._"
...

在此设置的原因可能是其他 console 任务现在会使用该值。通过查看 inspect actual 的反向依赖输出，可看到哪些使用了我们的新设置：

$ sbt inspect actual Global/initialCommands
...
[info] Reverse dependencies:
[info]  Compile / console
[info]  consoleProject
[info]  Test / console
[info]  Test / consoleQuick
[info]  Compile / consoleQuick
...

现在可知，通过在整个项目上设置 initialCommands，会影响该项目所有配置中的全部 console 任务。若不想让初始命令应用于 consoleProject（其无法使用我们项目的 classpath），可使用更具体的任务轴：

> set console / initialCommands := "import mypackage._"
> set consoleQuick / initialCommands := "import mypackage._"`

或配置轴：

> set Compile/　initialCommands := "import mypackage._"
> set Test / initialCommands := "import mypackage._"

下一部分描述 Delegates 部分，显示作用域的委托链。

委托

设置有键和作用域。若作用域 A 未定义键的值，对该键的请求可能委托给另一作用域。委托链是明确定义的，在 inspect 命令的 Delegates 部分显示。Delegates 部分显示当请求的键未定义值时搜索作用域的顺序。

例如，再次考虑 console 的初始命令：

$ sbt inspect console/initialCommands
...
[info] Delegates:
[info]  console / initialCommands
[info]  initialCommands
[info]  ThisBuild / console / initialCommands
[info]  ThisBuild / initialCommands
[info]  Zero / console / initialCommands
[info]  Global / initialCommands
...

这意味着若没有专门针对 console/initialCommands 的值，将按顺序搜索 Delegates 下列出的作用域，直到找到已定义的值。

Inspect tree

除显示上一节所述的直接正向和反向依赖外，inspect tree 命令还可显示任务或设置的完整依赖树。例如：

$ sbt inspect tree console
[info] Compile / console = Task[void]
[info]   +-Global / cleanupCommands =
[info]   +-console / compilers = Task[class xsbti.compile.Compilers]
[info]   +-Compile / fullClasspath = Task[Seq[class sbt.internal.util.Attributed]]
[info]   +-Global / initialCommands =
[info]   +-scalaInstance = Task[class sbt.internal.inc.ScalaInstance]
[info]   +-Compile / scalacOptions = Task[Seq[class java.lang.String]]
[info]   +-Compile / console / streams = Task[interface sbt.std.TaskStreams]
[info]   | +-Global / streamsManager = Task[interface sbt.std.Streams]
[info]   |
[info]   +-Global / taskTemporaryDirectory = target/....
[info]   +-Global / fileConverter = sbt.internal.inc.MappedFileConverter@10095d95
[info]   +-Global / state = Task[class sbt.State]
[info]
[success] elapsed: 0 s

对于每个任务，inspect tree 显示该任务生成值的类型。对于设置，显示其 toString。

The Book of sbt