使用 Bevy main 开发分支

Bevy 的开发速度非常快,经常有一些令人兴奋的新东西还没有发布。本页将介绍关于使用 Bevy 开发版本的的建议。

快速入门

如果你不使用任何第三方插件,只想使用 Bevy 主开发分支:

[dependencies]
bevy = "0.6"

[patch.crates-io]
bevy = { git = "https://github.com/bevyengine/bevy" }

欲了解更多信息,请继续阅读。

你需要使用 Bevy main 开发分支吗?

目前,Bevy 不做补丁版本发布,只做主版本发布。最新的版本往往缺少最新的错误修复、可用性改进和功能。加入到这个行动中来可能会很有说服力!

如果你是 Bevy 的新手,这可能不适合你;你可能更愿意使用已经发布的版本。它将拥有与社区插件和文档的最佳兼容性。

使用未发布版本的 Bevy 的最大缺点是第三方插件的兼容性。Bevy 是不稳定的、破坏性的,变化经常发生。然而,许多积极维护的社区插件都有跟踪最新的 Bevy 主分支,尽管它们可能不是完全最新的。有可能你想使用的插件在 Bevy main 分支的最新变化下不能工作,你可能要自己去修复它。

不过,频繁的破坏性变化对你来说可能不是一个问题。多亏了 Cargo,你可以在你方便的时候更新 Bevy,只要你觉得已经准备好处理任何可能的破坏性变化。

如果你选择使用 Bevy main 分支,我们强烈建议你在 DiscordGitHub 上 与 Bevy 社区互动,这样你就可以跟踪最新发生的事情,获得帮助,或参与讨论。

常见的陷阱:神秘的编译错误

当在不同版本的 Bevy 之间转换时(例如,将现有的项目从发布的版本过渡到 git 版本),你可能会遇到很多奇怪的意外构建错误。

通常你可以通过删除 Cargo.locktarget 目录来解决这些问题。

rm -rf Cargo.lock target

更多信息请看 这一页。关于这个错误,请看这个 cargo issue

如果你仍然出错,可能是因为 cargo 试图在你的依赖树中同时使用多个不同版本的 Bevy。如果你使用的一些插件指定了与你的项目不同的 Bevy版本,就会发生这种情况。这很烦人,但很容易解决。请阅读下面一节,了解如何配置你的项目,以尽量减少这种情况的发生。

如何使用 Bevy main 分支?

推荐的方法是使用 cargo patch

[dependencies]
# keep this as normal
bevy = "0.6"

[patch.crates-io]
# override it with bevy from git
bevy = { git = "https://github.com/bevyengine/bevy" }
# or if you have it cloned locally:
#bevy = { path = "../bevy" }

这样做会告诉 cargo 替换整个依赖树中的 Bevy 版本,包括第三方插件(假设它们也在其依赖中列出了 crates-io 的版本(bevy = "0.6"))。

如果你使用的任何第三方插件指定了不同的版本,这比直接在 [dependencies] 中指定 gitpath更好,因为这避免了在你的依赖树中可能有多个不同 bevy 版本的风险。

不幸的是,有些插件作者直接将 git 版本放在他们的 [dependencies] 中,这就破坏了上述设置。这可以通过添加另一个 cargo patch 来解决,也可以覆盖 git 仓库:

[patch."https://github.com/bevyengine/bevy"]
bevy = { path = "../bevy" }

一些第三方插件依赖于特定的 bevy 子模块,而不是整个 bevy。你可能还需要对这些插件单独打补丁:

[patch.crates-io]
bevy = { path = "../bevy" }
# specific crates as needed by the plugins you use (check their `Cargo.toml`)
bevy_ecs = { path = "../bevy/crates/bevy_ecs" }
bevy_math = { path = "../bevy/crates/bevy_math" }
# ... and so on

更新 Bevy

Cargo.lock 文件记录了你正在使用的确切版本(包括 git 提交)。在你手动更新 bevy 之前,bevy 的最新变化不会在你的项目中生效。

要更新,请运行:

cargo update

如果你删除或丢失了 Cargo.lock 文件,cargo 将不得不重新生成它并在这个过程中更新你的 bevy。为了防止这种情况,你应该把它和你的源代码一起添加到你的 git 仓库。另外,你也可以更明确地要求在 Cargo.toml 中提供准确的 git commit 哈希值。

bevy = { git = "https://github.com/bevyengine/bevy", rev = "7a1bd34e" }

给插件开发者的建议

如果你正在发布一个 bevy 插件,并且你想支持 bevy 主版本,建议你:

  • 在你的仓库中做一个单独的分支,以保持它与你的主版本分开,用于发布 bevy 的版本。
  • 在你的 README 中写上信息,告诉人们如何找到它。
  • 如上所示,配置你的 Cargo.toml。
  • 设置好 CI,当你的插件被 bevy 的新变化破坏时,能及时通知你。

有关 Cargo.toml 和依赖

如本页所示的 Cargo.toml 来发布你的插件。

通过指定 bevy 的发布版本,甚至在你跟踪 bevy 主分支的插件分支中,你可以让你的用户的开发变得更轻松。如果他们想使用本地的克隆版本、特定的提交版本或自己的分叉版本(而不是上游仓库),他们只需要在自己项目中打一个简单的 cargo 补丁就可以轻松做到。

如果你在依赖关系中直接指定 bevy git 仓库,你会使这种工作流程变得更加困难。

你也可以使用安全的方法引入 cargo 补丁。当你在开发你的插件时,这些补丁也能正常适用,你就可以根据想要的 bevy 版本进行构建,而不会影响你的用户,让他们使用他们想要的任何 bevy。

CI 配置

这里有一个 GitHub Actions 的例子。这个例子会在每天上午 8:00(UTC)运行,以验证你的代码是否仍可正常编译。如果失败,GitHub 会通知你。

name: check if code still compiles

on:
  schedule:
    - cron: '0 8 * * *'

env:
  CARGO_TERM_COLOR: always

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install Dependencies
        run: sudo apt-get update && sudo apt-get install --no-install-recommends pkg-config libx11-dev libasound2-dev libudev-dev

      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          override: true

      - name: Check code
        run: cargo update && cargo check --lib --examples