Lib.rs

› 开发工具
#lib #example #project #rust

rust_lib_example

Rust 项目示例

由 Nicolas Ferré 提供

2 个不稳定版本

0.2.0 2021 年 5 月 2 日
0.1.0 2021 年 4 月 14 日

#1413 in 开发工具

MIT/Apache

14KB
175 行

Rust 项目示例

Crates.io Docs.rs License CI Coverage with grcov Mutation tested with mutagen Lines of code

目的

该仓库包含 Rust 项目结构的示例。

大部分组件可以用于您的项目。

  • 项目配置
  • CI 工作流程，用于构建、代码检查、测试、检查测试覆盖率并运行突变测试
  • CD 工作流程，用于在所有平台上测试并在 crates.io 上发布

Github Actions 工作流程

作业

当在 main 分支上提交或发起拉取请求时，将触发 CI 工作流程，并运行以下作业

  • 测试 crate
    • 为所有目标构建项目并使用默认功能以确保一切都能编译
    • 使用默认功能运行单元测试、集成测试和文档测试
  • 运行测试覆盖率和突变测试
    • 使用 grcov 运行基于源代码的覆盖率，并使用 grcov
    • 在流程工件中上传 HTML 覆盖率报告
    • 在 Codecov 上上传 HTML 覆盖率报告
    • 如果未达到覆盖率阈值则失败
    • 使用 mutagen 运行突变测试（请注意，作业会自动添加 #[mutate] 注释）
    • 如果未达到突变阈值则失败
  • 运行多个代码检查
    • 运行 clippy
    • 运行 rustfmt 检查代码是否格式正确
    • 运行 cargo-deny 检查依赖项
    • 检查所有文件是否使用 UTF-8 编码
    • 检查所有行尾是否为 LF
    • 检查 Rust 代码中没有遗留 TODO

此工作流程仅在 Ubuntu 虚拟环境中运行。

当手动触发 CD 工作流程时，将运行以下作业

  • 检查 Cargo.toml 文件中的版本以发布
  • 在 Ubuntu 上测试
  • 在 Windows 上测试
  • 在 MacOS 上测试
  • 在 crates.io 上进行发布预演
  • 在 crates.io 上发布
  • 创建发布并准备下一个版本
    • 在 CHANGELOG.md 文件中更新最新版本及其发布日期并推送更改
    • 使用发布的版本名称标记创建的提交
    • 从创建的标记和 CHANGELOG.md 文件的内容创建 GitHub 发布
    • 在 CHANGELOG.md 文件中为下一个版本创建一个新的部分，并推送更改

密钥

CD 工作流需要以下密钥

  • CRATES_IO_TOKEN：在 crates.io 上发布 crate(s) 的令牌
  • GIT_TOKEN：GitHub 个人访问令牌，允许以管理员身份推送更改（如果 main 分支受保护，设置中必须取消选中“包括管理员”）

这些密钥必须存储在名为 Deployment 的 仓库环境 中。

设置

可以在文件 .github/workflows/ci.yml 中的 env 部分修改 CI 工作流的设置

  • RUST_VERSION_STABLE：要使用的稳定 Rust 编译器的版本
  • RUST_VERSION_NIGHTLY：当需要时使用的夜间 Rust 编译器的版本
  • MUTAGEN_COMMIT：要安装的 mutagen 版本的提交（来自 mutagen 仓库）
  • COV_THRESHOLD：覆盖率必须达到的最小阈值才能使作业成功
  • MUTAGEN_THRESHOLD：突变测试必须达到的最小阈值才能使作业成功
  • CRATE_PATHS：如果仓库是 Cargo 工作空间，则按发布顺序以 ; 分隔的包名称，否则为 .

可以在文件 .github/workflows/cd.yml 中的 env 部分修改 CD 工作流的设置

  • RUST_VERSION_STABLE：要使用的稳定 Rust 编译器的版本
  • CRATE_PATHS：如果仓库是 Cargo 工作空间，则按发布顺序以 ; 分隔的包名称，否则为 .

本地运行

可以使用 act 在您的机器上运行工作流。
安装后，在仓库文件夹中运行 act -P ubuntu-18.04=nektos/act-environments-ubuntu:18.04 来运行所有支持的工作。

工作空间

此仓库包含单个 crate，但工作流也应该与 Cargo 工作空间一起工作。

对其他项目的适配

此项目示例是为了重复使用而制作的。如果您对使用此模板感兴趣，可以复制您的项目中的文件，并在

  • 在文件 .github/workflows/ci.yml 中的 env 部分调整 CI 工作流的设置
  • 在文件 .github/workflows/cd.yml 中的 env 部分调整 CD 工作流的设置
  • 根据需要编辑 .lints、deny.toml、rustfmt.toml、Cargo.toml 和 README.md 文件
  • 根据需要编辑 .github/ISSUE_TEMPLATE 中的问题模板
  • 重置 CHANGELOG.md 文件（确保至少有一个部分 ## [Unreleased] - yyyy-mm-dd）
  • 如果您保留这些许可证，请更改 LICENSE-MIT 和 LICENSE-APACHE 文件中的版权声明
  • 在仓库设置中，创建一个名为 Deployment 的GitHub环境，并使用 CRATES_IO_TOKEN 和 GIT_TOKEN 秘密
  • 如果 main 分支被配置为受保护，请确保配置中没有勾选 Include administrators

许可证

在以下任一许可证下授权：

任选其一。

贡献

除非您明确声明，否则您有意提交以供包含在作品中的任何贡献，根据 Apache-2.0 许可证的界定，应按上述方式双授权，不附加任何额外条款或条件。

依赖项