sbt

有关基础介绍，请参阅入门指南中的基本任务。

概要

sbt
sbt command args
sbt --server
sbt --script-version

描述

sbt 是最初为 Scala 和 Java 创建的简单构建工具。它让我们声明子项目及其各种依赖和自定义任务，以确保始终获得快速、可重复的构建。

sbt runner 和 sbt server

  • sbt runner 是名为 sbt 的系统 shell 脚本，Windows 上为 sbt.bat。它能够运行_任意版本的 sbt_。有时也称为 "sbt-the-shell-script"。
    • 当检测到 sbt 2.x 时，sbt runner 以客户端模式执行，通常使用 sbtn（瘦客户端程序的 GraalVM 原生实现）。
    • sbt runner 还执行 sbt launcher，该启动器能够运行 任意版本的 sbt。
    • 当您从安装程序安装 sbt 时，您安装的是 sbt runner。
  • sbt server 是 sbt 的主要构件，也是实际的构建工具。
    • sbt 版本由每个工作目录中的 project/build.properties 确定。
    • sbt server 接受来自 sbtn、网络 API 或通过其自身 sbt shell 的命令。
sbt.version=2.0.0-RC9

此机制允许将构建配置为特定版本的 sbt，项目中的每个人都会使用相同的构建语义，无论其机器上安装的 sbt runner 是什么。

这也意味着某些功能在 sbt runner 或 sbtn 级别实现，而其他功能在 sbt server 级别实现。

sbt 命令

关于命令的说明

在 sbt 中，有在子项目级别操作的任务（如 compile），以及狭义上的命令（如 set），后者能够操作构建定义本身。

鉴于设置和任务被提升到 act 命令中，我们可以将 所有可输入 sbt shell 的内容 视为广义上的命令。 详见命令 概念页。

子项目级任务

  • clean 删除所有生成的文件（target 目录）。
  • publish 将构件（如 JAR）发布到由 publishTo 设置定义的仓库。
  • publishLocal 将构件（如 JAR）发布到本地 Ivy 仓库，如发布章节所述。
  • update 解析并获取外部依赖。

配置级任务

配置级任务是与配置关联的任务。例如，compile（等价于 Compile/compile）编译主源代码（Compile 配置）。Test/compile 编译测试源代码（Test 配置）。Compile 配置的大多数任务在 Test 配置中都有等效项，可使用 Test/ 前缀运行。

  • compile 编译主源代码（在 src/main/scala 目录中）。Test/compile 编译测试源代码（在 src/test/scala/ 目录中）。

  • console 使用包含编译源、lib 目录中所有 JAR 和托管库的 classpath 启动 Scala 解释器。返回 sbt 请输入 :quit、Ctrl+D（Unix）或 Ctrl+Z（Windows）。同样，Test/console 使用测试类和 classpath 启动解释器。

  • doc 使用 scaladoc 为 src/main/scala 中的 Scala 源文件生成 API 文档。Test/doc 为 src/test/scala 中的源文件生成 API 文档。

  • package 创建包含 src/main/resources 中文件和从 src/main/scala 编译的类的 JAR 文件。Test/package 创建包含 src/test/resources 中文件和从 src/test/scala 编译的类的 JAR。

  • packageDoc 创建包含从 src/main/scala 中 Scala 源文件生成的 API 文档的 JAR 文件。Test/packageDoc 创建包含 src/test/scala 中测试源文件 API 文档的 JAR。

  • packageSrc：创建包含所有主源文件和资源的 JAR 文件。打包路径相对于 src/main/scala 和 src/main/resources。同样，Test/packageSrc 对测试源文件和资源进行操作。

  • run <argument>* 在与 sbt 相同的虚拟机中运行项目的主类。主类接收提供的参数。

  • runMain <main-class> <argument>* 在与 sbt 相同的虚拟机中运行项目指定的主类。主类接收提供的参数。

  • test <test>* 运行指定的测试（或未提供参数时运行所有测试），包括：

    1. 尚未运行，或
    2. 上次运行失败，或
    3. 自上次成功运行以来有任何传递依赖被重新编译
      * 在测试名称中解释为通配符。

  • testFull 运行测试编译期间检测到的所有测试。

通用命令

  • shutdown 关闭 sbt server 以结束当前 sbt 会话。
  • exit 或 quit 结束当前交互式会话或构建。此外，Ctrl+D（Unix）或 Ctrl+Z（Windows）将退出交互式提示符。
  • help <command> 显示指定命令的详细帮助。若命令不存在，help 会列出名称或描述与参数（解释为正则表达式）匹配的命令的详细帮助。若未提供命令，则显示主要命令的简要描述。相关命令包括任务和设置。
  • projects [add|remove <URI>] 若无参数则列出所有可用项目，或添加/移除指定 URI 的构建。

  • Watch 命令 ~ <command> 在源文件变更时执行项目指定的操作或方法。

  • < filename 执行给定文件中的命令。每个命令应单独一行。空行和以 '#' 开头的行将被忽略

  • A ; B 执行 A，若成功则运行 B。注意前导分号是必需的。

  • eval <Scala-expression> 计算给定的 Scala 表达式并返回结果和推断类型。可用于设置系统属性、作为计算器、fork 进程等。例如：

    > eval System.setProperty("demo", "true")
> eval 1+1
> eval "ls -l" !

管理构建定义的命令

  • reload [plugins|return] 若未指定参数，则重新加载构建，必要时重新编译任何构建或插件定义。reload plugins 将当前项目改为构建定义项目（在 project/ 中）。这可用于直接操作构建定义。例如，在构建定义项目上运行 clean 将强制更新快照并重新编译构建定义。reload return 切换回主项目。

  • set <setting-expression> 计算并应用给定的设置定义。该设置一直有效，直到 sbt 重启、构建重新加载，或被另一个 set 命令覆盖或被 session 命令移除。

  • session <command> 管理由 set 命令定义的会话设置。可持久化在提示符处配置的设置。

  • inspect <setting-key> 显示有关设置的信息，如值、描述、定义作用域、依赖、委托链和关联设置。

sbt runner 和 launcher

从系统 shell 启动 sbt runner 时，可指定各种系统属性或 JVM 额外选项以影响其行为。

sbt JVM 选项和系统属性

若在 sbt 启动时定义了 JAVA_OPTS 和/或 SBT_OPTS 环境变量，其内容将作为命令行参数传递给运行 sbt server 的 JVM。

若当前目录存在名为 .jvmopts 的文件，其内容在 sbt 启动时追加到 JAVA_OPTS。同样，若存在 .sbtopts 和/或 /etc/sbt/sbtopts，其内容追加到 SBT_OPTS。JAVA_OPTS 的默认值为 -Dfile.encoding=UTF8。

您也可以直接以 sbt 参数形式指定 JVM 系统属性和命令行选项：任何 -Dkey=val 参数将原样传递给 JVM，任何 -J-Xfoo 将作为 -Xfoo 传递。

另请参阅 sbt --help 获取更多详情。

sbt JVM 堆、permgen 和栈大小

若您发现 permgen 空间不足或工作站内存不足，请像对待任何 Java 应用一样调整 JVM 配置。

例如，常见的内存相关选项集为：

export SBT_OPTS="-Xmx2048M -Xss2M"
sbt

或若您希望仅为此会话指定：

sbt -J-Xmx2048M -J-Xss2M

启动目录

sbt runner 仅是引导程序，实际的 sbt server、Scala 编译器和标准库默认下载到共享目录 $HOME/.sbt/boot/。

要更改此目录位置，请设置 sbt.boot.directory 系统属性。相对路径将相对于当前工作目录解析，若您希望避免在项目间共享启动目录，这会很有用。例如，以下使用将启动目录放在 project/boot/ 的 0.11 之前风格：

sbt -Dsbt.boot.directory=project/boot/

终端编码

您终端使用的字符编码可能与您平台上 Java 的默认编码不同。在这种情况下，您需要指定file.encoding=<encoding> 系统属性，可能类似：

export JAVA_OPTS="-Dfile.encoding=Cp1252"
sbt

HTTP/HTTPS/FTP 代理

在 Unix 上，sbt 会从标准环境变量 http_proxy、https_proxy 和 ftp_proxy 获取 HTTP、HTTPS 或 FTP 代理设置。若您在使用需要认证的代理后面，需在 sbt 启动时传递一些补充标志。详见 JVM networking system properties。

例如：

sbt -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

在 Windows 上，您的脚本应设置代理主机、端口的属性，如适用还包括用户名和密码。例如，对于 HTTP：

sbt -Dhttp.proxyHost=myproxy -Dhttp.proxyPort=8080 -Dhttp.proxyUser=username -Dhttp.proxyPassword=mypassword

将上述命令行中的 http 替换为 https 或 ftp 以配置 HTTPS 或 FTP。

其他系统属性

以下系统属性也可传递给 sbt runner：

-Dsbt.banner=true

显示宣传新功能的欢迎横幅。

-Dsbt.ci=true

默认为 false（除非设置了环境变量 BUILD_NUMBER）。用于持续集成环境。抑制 supershell 和颜色。

-Dsbt.client=true

运行 sbt 客户端。

-Dsbt.color=auto

  • 要开启颜色，使用 always 或 true。
  • 要关闭颜色，使用 never 或 false。
  • 若输出是支持颜色的终端（非管道）则使用颜色，使用 auto。

-Dsbt.coursier.home=$HOME/.cache/coursier/v1

Coursier 构件缓存的位置，默认由 Coursier cache resolution logic 定义。您可使用 csrCacheDirectory 命令验证该值。

-Dsbt.genbuildprops=true

若缺失则生成 build.properties。若未设置，则遵从 sbt.skip.version.write。

-Dsbt.global.base=$HOME/.sbt/

包含全局设置和插件的目录。

-Dsbt.override.build.repos=true

若为 true，则忽略构建定义中配置的仓库，改用为 launcher 配置的仓库。

-Dsbt.repository.config=$HOME/.sbt/repositories

包含 launcher 使用的仓库的文件。格式与 sbt launcher 配置文件的 [repositories] 部分相同。此设置通常与将 sbt.override.build.repos 设为 true 配合使用。