sbt-revolver 使用与技术文档

2024-12-27 09:16:02作者：尤峻淳Whitney

1. 安装指南

sbt-revolver 是一款为 SBT 提供的插件，能够为您的 Scala 应用程序实现超快速的开发周转。

要安装 sbt-revolver，您需要在项目中的 project/plugins.sbt 文件中添加以下依赖：

addSbtPlugin("io.spray" % "sbt-revolver" % "0.10.0")

sbt-revolver 是一个自动插件，因此您无需在 build.sbt 或 Build.scala 中进行额外配置即可使用。在多模块构建中，它将为每个模块启用。若要在某些子模块中禁用 sbt-revolver，请在构建文件中使用 Project(...).disablePlugins(RevolverPlugin)。

对于较旧的 SBT 版本，请查看版本 0.9.1。

2. 项目使用说明

sbt-revolver 在其自己的 re 配置中定义了三个新的命令（SBT 任务）：

reStart <args> --- <jvmArgs>：在后台的交互式 SBT shell（在一个独立的 JVM 中）启动您的应用程序。可选的 JVM 参数将附加到通过 reStartArgs/reStart::javaOptions 设置配置的参数后面。如果应用程序已经在运行，它将首先停止，然后重新启动。
reStop：停止应用程序。这是通过强制终止分叉的 JVM 来完成的。请注意，这意味着 shutdown hooks 将不会被运行。
reStatus：显示有关应用程序当前运行状态的信息。

触发重启

您可以使用 ~reStart 进入“触发重启”模式。应用程序启动后，SBT 会监视您的源（或资源）文件的变化。如果检测到变化，SBT 将重新编译所需的类，并且 sbt-revolver 会自动重新启动您的应用程序。当您按下 <ENTER> 时，SBT 会退出“触发重启”模式并返回到正常提示符，同时保持您的应用程序运行。

要自定义哪些文件应触发重启，请参阅 SBT 文档中的 Triggered Execution。

3. 项目API使用文档

本项目主要提供以下API：

reStart <args> --- <jvmArgs>：启动应用程序
reStop：停止应用程序
reStatus：查看应用程序状态

更多详细配置和使用方式，请参考下文。

4. 项目安装方式

请参考上文“安装指南”部分。

以下是关于项目配置的详细信息：

配置

以下是由 sbt-revolver 定义的可能感兴趣的 SBT 设置：

reStartArgs：允许您定义每次启动时 sbt-revolver 应传递给您的应用程序的参数。
reStart / mainClass：允许您为 reStart 定义一个主类，独立于正常运行项目时设置的主类。
reStart / javaOptions：允许您定义传递给分叉 JVM 的选项。
reStart / baseDirectory：允许您独立于 run 设置的目录自定义基本目录。
reStart / fullClasspath：允许您自定义用于运行的完整类路径。
reStart / envVars：允许您自定义运行应用程序时的环境变量。
reJrebelJar：允许您覆盖 JREBEL_PATH 环境变量的值。
reColors：允许您更改用于标记运行进程输出的颜色。
reLogTag：允许您更改日志消息前的日志标签。
debugSettings：允许您指定远程调试器设置。

示例

设置应用程序的 2 GB 内存限制：
```
reStart / javaOptions += "-Xmx2g"
```

为 reStart 设置特殊的主类：

reStart / mainClass := Some("com.example.Main")

设置固定的启动参数：
```
reStartArgs := Seq("-x")
```

启用调试：

Revolver.enableDebugging(port = 5050, suspend = true)

更改用于标记输出的颜色：

reColors := Seq("blue", "green", "magenta")

添加环境变量：

reStart / envVars := Map("USER_TOKEN" -> "2359298356239")

热重载

注意：sbt-revolver 中对 JRebel 的支持已不再积极维护。

如果您已安装 JRebel，可以通过设置 Revolver.jRebelJar 在 SBT 配置中告知 sbt-revolver jrebel.jar 的位置，或者通过名为 JREBEL_PATH 的环境变量来设置（这是推荐的方式，因为它不会在您的 SBT 配置中污染系统特定的设置）。

使用 JRebel，sbt-revolver 支持热重载：

使用 reStart 启动应用程序。
使用 ~products 进入“触发编译”模式。SBT 会监视您的源（和资源）文件的变化。如果检测到变化，SBT 会重新编译所需的类，JRebel 会将更改的类直接加载到运行中的应用程序中。由于应用程序没有重新启动，因此将更改实时生效所需的时间是最小的。当您按下 <ENTER> 时，SBT 会退出“触发编译”模式并返回到正常提示符，同时保持应用程序运行。
如果您以需要完全重启的方式更改了应用程序，请按 <ENTER> 退出“触发编译”模式并使用 reStart。
当然，您随时可以使用 reStop 停止应用程序。