cargo-remark

Cargo 子命令，可让您查看编译您的 crate 时生成的 LLVM 优化备注。

这些备注可以告诉您 LLVM 在何处以及为什么未能应用某些优化。在某些情况下[^1]，您可以使用这些知识来修改代码，以便它优化得更好。将来，我希望 rustc 能够生成自己的、针对 Rust 的（MIR？）优化备注，但这只是一个想法。

[^1]: 目前可能只有如果您是 LLVM 专家。

cargo remark 编译您的 crate，生成 LLVM 备注，然后解析并将它们可视化在简单的网站上。它是并行化的，这对于大型程序很重要，因为可能会有很多备注，并且由于它们是 YAML 格式，解析速度不快。

欢迎贡献！

生成输出示例

安装

$ cargo install cargo-remark

请注意，rustc 在 2023 年 2 月 7 日 获得了 输出 YAML 格式的 LLVM 优化备注的能力，但目前还不稳定。因此，您需要编译器的最新夜间版本[^2] 来生成 LLVM 备注。

$ rustup update nightly

[^2]: 至少 nightly-2023-07-03-...。

使用方法

rustc 可以使用（目前不稳定）的 --dir 标志来生成 LLVM 备注，该标志是该 crate 内部使用的。要从您的 crate 中生成备注，请使用以下命令

$ cargo remark build

构建完成后，备注将位于 target/remarks/yaml，而渲染的网站将位于 target/remarks/web。您可以通过将网页浏览器指向 target/remarks/web/index.html 文件或使用 --open 标志来打开网站。

此命令将自动构建您的crate，并启用优化，因此您无需传递 --release 标志。目前，只有遗漏的优化备注将被可视化。《分析》和《通过》备注将被忽略。

CLI参数

功能

目前有一个功能 mimalloc，默认启用，它启用了 mimalloc 分配器的使用。要禁用功能，请使用 --no-default-features 编译（或安装）crate。

从目录渲染备注

如果您有一个包含YAML备注的目录，并且只想在没有调用Cargo的情况下可视化它们，可以使用此crate附带 的 analyze-remarks 二进制文件。

$ analyze-remarks <yaml-dir> --source-dir <crate root>

当您使用此工具时，您需要手动传递从备注生成的根源目录（使用 cargo remark，它将自动推断）。

您甚至可以使用此二进制文件来渲染来自C/C++程序生成的备注。这样做的优点是，analyze-remarks 可能比 现有的 C/C++ 备注工具（用Python编写的）要快得多。

与PGO一起使用

如果您使用 Profile-guided optimization (PGO) 编译您的crate，生成的备注将包含“热度”，这是衡量每个遗漏的优化备注重要性的度量。这可以帮助您优先处理哪些备注应首先解决。

您可以将 cargo remark 与 cargo-pgo 命令结合使用，以从PGO优化的构建中生成备注

# Compile with PGO instrumentation
$ cargo pgo build

# Gather PGO profiles
$ ./target/release/<target>/<binary> <workload>

# Compile with PGO optimizations and generate remarks
$ cargo remark wrap -- pgo optimize

相关工作

此crate，特别是生成的网站，受到了 optview2 的大力启发，这是一个用于可视化从C和C++程序生成的LLVM优化备注的工具。

许可

MIT