docs.rs 即将进行的更改

2019 年 9 月 18 日 · Rust 基础设施团队

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 AlbiniOnur Aslan 完成,QuietMisdreavusMark Rousskov 审查了这些更改。