89 个版本 (16 个重大变更)
| 新 0.17.0 | 2024 年 8 月 23 日 |
|---|---|
| 0.16.8 | 2024 年 7 月 30 日 |
| 0.15.2 | 2024 年 3 月 28 日 |
| 0.13.2 | 2023 年 12 月 27 日 |
| 0.2.2 | 2016 年 6 月 30 日 |
在 Cargo 插件 中排名 28
每月下载量 2,077 次
被 kabwoy_auth_service 使用
295KB
4K SLoC
cargo-modules
概述
用于可视化/分析软件包内部结构的 cargo 插件。
动机
随着时间的推移，随着 Rust 项目的不断壮大，正确地组织代码变得越来越重要。幸运的是，Rust 提供了一个相当复杂的模块系统，允许我们将软件包分成任意小的子模块，包括类型和函数。虽然这有助于避免单调、无结构的代码块，但有时也难以在心理上掌握当前项目的高层整体结构。
这就是 cargo-modules 发挥作用的地方
安装
通过以下方式安装 cargo-modules
cargo install cargo-modules
使用方法
cargo-modules 工具提供了一些命令
# Print a crate's hierarchical structure as a tree:
cargo modules structure <OPTIONS>
# Print a crate's internal dependencies as a graph:
cargo modules dependencies <OPTIONS>
# Detect unlinked source files within a crate's directory:
cargo modules orphans <OPTIONS>
命令帮助
$ cargo modules --help
Visualize/analyze a crate's internal structure.
Usage: cargo-modules <COMMAND>
Commands:
structure Prints a crate's hierarchical structure as a tree.
dependencies Prints a crate's internal dependencies as a graph.
orphans Detects unlinked source files within a crate's directory.
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
cargo modules structure
以树的形式打印软件包的层次结构
cargo modules structure <OPTIONS>
命令帮助
$ cargo modules structure --help
Prints a crate's hierarchical structure as a tree.
Usage: cargo-modules structure [OPTIONS]
Options:
--verbose Use verbose output
--lib Process only this package's library
--bin <BIN> Process only the specified binary
-p, --package <PACKAGE> Package to process (see `cargo help pkgid`)
--no-default-features Do not activate the `default` feature
--all-features Activate all available features
--features <FEATURES> List of features to activate. This will be ignored if `--cargo-all-features` is provided
--target <TARGET> Analyze for target triple
--manifest-path <MANIFEST_PATH> Path to Cargo.toml [default: .]
--no-fns Filter out functions (e.g. fns, async fns, const fns) from tree
--no-traits Filter out traits (e.g. trait, unsafe trait) from tree
--no-types Filter out types (e.g. structs, unions, enums) from tree
--sort-by <SORT_BY> The sorting order to use (e.g. name, visibility, kind) [default: name]
--sort-reversed Reverses the sorting order
--focus-on <FOCUS_ON> Focus the graph on a particular path or use-tree's environment, e.g. "foo::bar::{self, baz, blee::*}"
--max-depth <MAX_DEPTH> The maximum depth of the generated graph relative to the crate's root node, or nodes selected by '--focus-on'
--cfg-test Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)
-h, --help Print help
示例：文本树形式的模块结构
cd ./tests/projects/readme_tree_example
cargo-modules structure --cfg-test
输出
crate readme_tree_example
├── trait Lorem: pub
├── mod amet: pub(crate)
│ └── mod consectetur: pub(self)
│ └── mod adipiscing: pub(self)
│ └── union Elit: pub(in crate::amet)
├── mod dolor: pub(crate)
│ └── enum Sit: pub(crate)
└── mod tests: pub(crate) #[cfg(test)]
└── fn it_works: pub(self) #[test]
(项目源代码: readme_tree_example/src/lib.rs)
终端颜色
如果您在支持颜色的终端上运行此命令，并且环境中没有定义 NO_COLOR，则输出将以颜色显示，以便更容易进行视觉解析
└── <visibility> <keyword> <name> [<test-attributes>]
以下颜色用于突出显示 <visibility> (更多信息)
| 颜色 | 意义 |
|---|---|
| 🟢 绿色 | 对所有和所有事物可见的项（例如，pub） |
| 🟡 黄色 | 当前crate可见的项（例如，pub(crate)） |
| 🟠 橙色 | 对一定父模块可见的项（例如，pub(in path)） |
| 🔴 红色 | 当前模块可见的项（例如，pub(self)，没有pub …时隐含） |
关键字<keyword>以 🔵 蓝色突出显示，以便从名称中视觉上区分。
受测试保护的项（例如，#[cfg(test)] …）和测试函数（例如，#[test] fn …）旁边打印它们的相应<test-attributes>，以灰色和青色显示。
cargo模块依赖
以图形方式打印crate的内部依赖
cargo modules dependencies <OPTIONS>
命令帮助
$ cargo modules dependencies --help
Prints a crate's internal dependencies as a graph.
Usage: cargo-modules dependencies [OPTIONS]
Options:
--verbose Use verbose output
--lib Process only this package's library
--bin <BIN> Process only the specified binary
-p, --package <PACKAGE> Package to process (see `cargo help pkgid`)
--no-default-features Do not activate the `default` feature
--all-features Activate all available features
--features <FEATURES> List of features to activate. This will be ignored if `--cargo-all-features` is provided
--target <TARGET> Analyze for target triple
--manifest-path <MANIFEST_PATH> Path to Cargo.toml [default: .]
--no-externs Filter out extern items from extern crates from graph
--no-fns Filter out functions (e.g. fns, async fns, const fns) from graph
--no-modules Filter out modules (e.g. `mod foo`, `mod foo {}`) from graph
--no-sysroot Filter out sysroot crates (`std`, `core` & friends) from graph
--no-traits Filter out traits (e.g. trait, unsafe trait) from graph
--no-types Filter out types (e.g. structs, unions, enums) from graph
--no-uses Filter out "use" edges from graph
--acyclic Require graph to be acyclic
--layout <LAYOUT> The graph layout algorithm to use (e.g. none, dot, neato, twopi, circo, fdp, sfdp) [default: neato]
--focus-on <FOCUS_ON> Focus the graph on a particular path or use-tree's environment, e.g. "foo::bar::{self, baz, blee::*}"
--max-depth <MAX_DEPTH> The maximum depth of the generated graph relative to the crate's root node, or nodes selected by '--focus-on'
--cfg-test Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)
-h, --help Print help
If you have xdot installed on your system, you can run this using:
`cargo modules dependencies | xdot -`
示例：图形模块结构
cargo modules dependencies --no-externs --no-fns --no-sysroot --no-traits --no-types --no-uses > mods.dot
（上述命令等同于从v0.12.0或更早版本中cargo-modules generate graph）
示例：图形依赖
cd ./tests/projects/smoke
cargo-modules dependencies --cfg-test | dot -Tsvg
See "./docs/dependencies_output.dot" for the corresponding raw dot file.
（项目源代码：readme_graph_example/src/lib.rs）
节点结构
各个节点按以下结构组织
┌────────────────────────┐
│ <visibility> <keyword> │
├────────────────────────┤
│ <path> │
└────────────────────────┘
节点颜色
以下颜色用于突出显示 <visibility> (更多信息)
| 颜色 | 意义 |
|---|---|
| 🔵 蓝色 | crates（即它们的隐式根模块） |
| 🟢 绿色 | 对所有和所有事物可见的项（例如，pub） |
| 🟡 黄色 | 当前crate可见的项（例如，pub(crate)） |
| 🟠 橙色 | 对一定父模块可见的项（例如，pub(in path)） |
| 🔴 红色 | 当前模块可见的项（例如，pub(self)，没有pub …时隐含） |
无环模式
cargo-modules的dependencies命令检查是否存在--acyclic标志。如果找到，它将在有向图中搜索循环，并在发现任何循环时返回错误。
在工具本身源上运行cargo modules dependencies --lib --acyclic会发出以下循环错误
Error: Circular dependency between `cargo_modules::options::general` and `cargo_modules::options::generate`.
┌> cargo_modules::options::general
│ └─> cargo_modules::options::generate::graph
│ └─> cargo_modules::options::generate
└──────────┘
cargo模块孤儿
检测crate目录中的未链接源文件
cargo modules orphans <OPTIONS>
命令帮助
$ cargo modules orphans --help
Detects unlinked source files within a crate's directory.
Usage: cargo-modules orphans [OPTIONS]
Options:
--verbose Use verbose output
--lib Process only this package's library
--bin <BIN> Process only the specified binary
-p, --package <PACKAGE> Package to process (see `cargo help pkgid`)
--no-default-features Do not activate the `default` feature
--all-features Activate all available features
--features <FEATURES> List of features to activate. This will be ignored if `--cargo-all-features` is provided
--target <TARGET> Analyze for target triple
--manifest-path <MANIFEST_PATH> Path to Cargo.toml [default: .]
--deny Returns a failure code if one or more orphans are found
--cfg-test Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)
-h, --help Print help
示例
cd ./tests/projects/readme_tree_example
cargo-modules structure --types --traits --fns --tests
输出
2 orphans found:
warning: orphaned module `foo` at src/orphans/foo/mod.rs
--> src/orphans.rs
| ^^^^^^^^^^^^^^ orphan module not loaded from file
|
help: consider loading `foo` from module `orphans::orphans`
|
| mod foo;
| ++++++++
|
warning: orphaned module `bar` at src/orphans/bar.rs
--> src/orphans.rs
| ^^^^^^^^^^^^^^ orphan module not loaded from file
|
help: consider loading `bar` from module `orphans::orphans`
|
| mod bar;
| ++++++++
|
Error: Found 2 orphans in crate 'orphans'
（项目源代码：readme_tree_example/src/lib.rs）
无色模式
cargo-modules检查是否存在NO_COLOR环境变量，无论其值如何，都会阻止将其添加到控制台输出（仅控制台输出！）。
贡献
请阅读CONTRIBUTING.md以了解我们的行为准则，
以及向我们提交拉取请求的过程。
版本控制
我们使用SemVer进行版本控制。有关可用版本，请参阅此存储库上的标签。
许可协议
本项目采用MPL-2.0 许可协议 – 详细信息请参阅LICENSE.md 文件。
依赖项
~27–37MB
~693K SLoC