Skip to content

Latest commit

 

History

History
145 lines (84 loc) · 6.82 KB

for-developers.md

File metadata and controls

145 lines (84 loc) · 6.82 KB

开发者注意事项(草案)

本文用于同步开发 zCore 的一些策略选择并提醒开发者某些需要注意的信息。

本文暂时是一份草案,欢迎在相关微信群或 github 讨论区发表对形式和内容的意见

目录

工具链支持策略

由于下文详述的具体原因,本项目依赖一些不稳定特性,只能使用 nightly 工具链编译。仓库将测试可用的工具链记录在 cargo 可识别的工具链配置文件,使用 cargo 构建项目时会自动安装可靠的工具链。

仓库使用的工具链虽然是 nightly 的,但将伴随 stable 工具链的版本更新而更新。每当 stable 工具链更新,就将默认工具链更新到最接近最新 stable 的版本,周期约为 6 周。参考版本信息网站记录的最新稳定版分叉发生时间,使用对应的 nightly 即可。

下一次更新的版本为 1.64(2022-08-05),进行更新的日期为 2022 年 9 月 22 日。

本文档记录的预期更新时间将随着每次工具链更新而更新。

使用的不稳定特性

用到的模块:zcore-driverskernel-halzcore-loader

用于在文档上标记对象可使用的平台信息。

标注有助于提升文档质量,但不影响使用,必要时可去除。

用到的模块:zcore

这三项用于支撑一个 rust 裸函数。裸函数不会自动插入栈操作,因此可用于设置栈之前的阶段。配合用于向内联汇编导入 rust 常量的 asm_const 和向内联汇编导入 rust 符号的 asm_sym,可以将整个启动阶段尽量置于 rust 的保护之下(避免硬编码常量或导出全局符号)。

可以移除,但不建议。

用到的模块:zcore

要求 alloc 提供一个默认的分配失败回调。

只要同时使用 no_stdalloc 就必然需要分配失败回调,可选默认的或通过另一个不稳定特性 alloc-error-handler 提供一个自定义的。

代码质量保障

代码质量主要依赖 clippy 来保障。因此,需要创造利于 clippy 运行的环境,这包括三个部分:

  1. rust-analyzer 绑定

    如果使用 vs code 开发,rust-analyzer 支持 checkOnSave 功能,即保存时自动检查(得益于现代编译器的效率,这是可能的)。如果配合自动保存功能,可实现随时检查,只要将检查方式默认为 clippy,即可随时 clippy。

    当然 clippy 运行比较慢,如果电脑性能不适应,只好关掉。

  2. #![deny(warnings)]

    这个选项将当前模块(当然也包括子模块)产生的警告视为错误,这会禁止产生警告的代码完成编译,有助于及早解决问题。clippy 也将产生警告,这些警告也被视作错误。

    目前,所有模块都添加了这个选项(有些还禁止了别的东西,unsafe_code 及 missing_docs 等,这不在我们的讨论范围内),且处在可通过编译的状态。开发时为了方便当然可以注释掉它们,但如果发布 PR,务必恢复这些选项。

  3. github actions

使用 clippy 检查代码已经写入 github 工作流,每次提交都会自动执行。这可以向其他开发者证明你的代码质量受到保障。可以在本地使用 cargo check-style 命令检查代码的合规性,其流程和使用 clippy 的方式与 github 工作流保持一致。

依赖管理策略

依赖从特殊到一般,分为以下 4 种形式:

  1. git 子模块
  2. 个人仓库中基于 cargo 的项目
  3. 组织仓库中基于 cargo 的项目
  4. 发布到 crates.io 上的 crate

git 子模块

最特殊的依赖方式,对于那些不使用 cargo(由于不是 rust 编写)的项目不得不如此。

目前使用此方式依赖的项目包括:

  • libc-test

    musl libc 的测例。使用 c 语言实现。

  • tests

    测试框架。主要使用 python。

  • rboot

    uefi 引导程序,使用 rust 实现。作为子模块是一个遗留问题,未来会解决。

个人仓库中基于 cargo 的项目

比较特殊的依赖方式,当且仅当一个项目具有下列情况之一:

  • 属于实验性质,不稳定甚至可能放弃;
  • 稳定,但不适合发布到 crates.io,也没有组织愿意收录;
  • 从组织项目分叉,已提交 PR 但尚未采纳;
  • 从组织项目分叉,且出于充分的理由决定永久分叉,成为一个独立的项目;

可以直接从个人项目中直接依赖。

如有可能,上述情况应当积极解决。

必须锁定提交哈希。

组织仓库中基于 cargo 的项目

正常的依赖方式,但若有可能,尽量发布到 crates.io。

必须锁定提交哈希。

发布到 crates.io 上的 crate

正常的依赖方式,可以随意使用。

尽量跟踪最新版本。对于无法跟踪的依赖,应记录理由。

features and cfg

zCore 支持多种平台的不同硬件,难以避免使用编译选项。但是不当使用编译选项,可能导致混乱,或者干扰测试的覆盖性。因此,建议遵从如下标准设置 #[cfg(...)]

  1. 仅与由平台决定的,设置 target_arch;

  2. 受到其他因素影响的,考虑通过设备树等方式动态决定;

  3. 无法动态决定的,可以设置 feature,但应在所在项目的入口(lib.rs 或 main.rs)注明设置 feature 的原因;

  4. 平台相关的 feature,应增加如下的约束,而不是使用 all(target_arch = ..., feature = ...)

    #[cfg(all(feature = "sbi", not(target_arch = "riscv64")))]
    compile_error!("`sbi` is only available on RISC-V platforms");

现有代码不完全满足以上标准,将逐步改正