9 月 30 日,破坏性更改将部署到 docs.rs 构建环境中。docs.rs 是一项免费服务,用于构建和托管在 crates.io 上发布的所有 crate 的文档。它是开源的,由 Rustdoc 团队维护,并由 基础设施团队运营。
将要发生什么变化
构建将在 rustops/crates-build-env Docker 镜像内执行。该镜像包含许多已安装的系统依赖项,以确保我们可以构建尽可能多的 crate。它已被 Crater 使用,并且我们添加了先前在旧构建环境中安装的所有依赖项。
为了确保我们将来可以继续运营该服务并提高其可靠性,我们还改进了执行构建的沙箱,添加了新的限制
- 每个平台现在将有 15 分钟的时间来构建其依赖项和文档。
- 构建将有 3 GB 的 RAM 可用。
- 网络访问将禁用(crates.io 依赖项仍将被获取)。
- 只有
target/
目录可写,并且每次构建后都会被清除。
最后,docs.rs 现在将在构建 crate 时使用最新的 nightly 版本,而不是使用手动更新的 nightly 版本。
如何为更改做好准备
要测试您的 crate 是否在新环境中构建,您可以在本地下载 Docker 镜像并在其中执行 shell
docker pull rustops/crates-build-env
docker run --rm --memory 3221225472 -it rustops/crates-build-env bash
进入 shell 后,您可以安装 rustup(默认情况下它没有安装在镜像中),安装 Rust nightly 版本,克隆您的 crate 的存储库,然后构建文档
cargo fetch
time cargo doc --no-deps
为了帮助您进行测试,这些命令会将可用 RAM 限制为 3 GB,并显示 cargo doc
的总执行时间,但网络访问不会被阻止,因为您需要获取依赖项。
如果您的项目需要构建环境中缺少系统依赖项,请在 Docker 镜像的 存储库上打开一个 issue,我们将考虑添加它。
如果您的 crate 由于生成文档的时间超过 15 分钟或使用了超过 3 GB 的 RAM 而无法构建,请打开一个 issue,我们将考虑为您的 crate 合理增加限制。但是,我们不会为您的 crate 启用网络访问:您需要更改您的 crate,使其在构建时不需要任何外部资源。
我们建议使用 Cargo features 来删除导致构建失败的代码部分,并使用 docs.rs 元数据启用这些功能。
致谢
新的构建环境基于 Rustwide,它是 Crater 的底层库。它从 Crater 代码库中提取出来,由 Crater 贡献者和 Rustwide 贡献者共同创建。
docs.rs 方面的实现工作由 Pietro Albini 和 Onur Aslan 完成,QuietMisdreavus 和 Mark Rousskov 审查了这些更改。