A cargo plugin for showing an overview of a crate's modules.
With time, as your Rust projects grow bigger and bigger, it gets more and more important to properly structure your code. Fortunately Rust provides us with a quite sophisticated module system, allowing us to neatly split up our crates into arbitrarily small sub-modules of types and functions. While this helps to avoid monolithic and unstructured chunks of code, it can also make it hard at times to still mentally stay on top of the over-all high-level structure of the project at hand.
This is where cargo-modules comes into play:
Install cargo-modules via:
bash
cargo install cargo-modules
bash
cargo modules generate tree <OPTIONS>
```terminal Usage: cargo-modules generate tree [OPTIONS]
Options:
--verbose Use verbose output
--lib Process only this package's library
--bin cargo help pkgid)
--no-default-features Do not activate the default feature
--all-features Activate all available features
--features --cargo-all-features is provided
--target #[cfg(test)] enabled
--no-cfg-test Analyze with #[cfg(test)] disabled. [default]
--sysroot Include sysroot crates (std, core & friends) in analysis
--no-sysroot Exclude sysroot crates (std, core & friends) in analysis. [default]
--manifest-path #[test] fn …)
--no-tests Exclude tests (e.g. #[test] fn …). [default]
--orphans Include orphaned modules (i.e. unused files in /src)
--no-orphans Exclude orphaned modules (i.e. unused files in /src). [default]
-h, --help Print help
```
The following image is the result of using the following command to generate a tree of the smoke test project within its own repo:
bash
cd ./tests/projects/smoke
cargo-modules generate tree --types --tests --orphans
The individual lines are structured as follows:
plain
└── <keyword> <name>: <visibility> <test-attributes>
The <keyword> is highlighted in 🔵 blue to visually separate it from the name.
Test modules and functions have their corresponding <test-attributes> (i.e. #[cfg(test)] / #[test]) printed next to them in gray and cyan.
The <visibility> (more info) is further more highlighted by the following colors:
| Color | Meaning |
| -------- | ---------------------------------------------------------------------------------- |
| 🟢 green | Items visible to all and everything (i.e. pub) |
| 🟡 yellow | Items visible to the current crate (i.e. pub(crate)) |
| 🟠 orange | Items visible to a certain parent module (i.e. pub(in path)) |
| 🔴 red | Items visible to the current module (i.e. pub(self), implied by lack of pub …) |
| 🟣 purple | Orphaned modules (i.e. a file exists on disk but no corresponding mod …) |
bash
cargo modules generate graph <OPTIONS>
```terminal Usage: cargo-modules generate graph [OPTIONS]
Options:
--verbose Use verbose output
--lib Process only this package's library
--bin cargo help pkgid)
--no-default-features Do not activate the default feature
--all-features Activate all available features
--features --cargo-all-features is provided
--target #[cfg(test)] enabled
--no-cfg-test Analyze with #[cfg(test)] disabled. [default]
--sysroot Include sysroot crates (std, core & friends) in analysis
--no-sysroot Exclude sysroot crates (std, core & friends) in analysis. [default]
--manifest-path #[test] fn …)
--no-tests Exclude tests (e.g. #[test] fn …). [default]
--orphans Include orphaned modules (i.e. unused files in /src)
--no-orphans Exclude orphaned modules (i.e. unused files in /src). [default]
--acyclic Require graph to be acyclic
--layout mod foo, mod foo {})
--modules Include modules (e.g. mod foo, mod foo {}). [default]
--uses Include used modules and types
--no-uses Exclude used modules and types [default]
--externs Include used modules and types from extern crates
--no-externs Exclude used modules and types from extern crates [default]
-h, --help Print help
If you have xdot installed on your system, you can run this using:
`cargo modules generate dependencies | xdot -`
```
The following image is the result of using the following command to generate a graph of the smoke test project within its own repo:
bash
cd ./tests/projects/smoke
cargo-modules generate graph --types --tests --orphans | dot -Tsvg
The individual nodes are structured as follows:
plain
┌────────────────────────┐
│ <visibility> <keyword> │
├────────────────────────┤
│ <path> │
└────────────────────────┘
The <visibility> (more info) is further more highlighted by the following colors:
| Color | Meaning |
| -------- | ---------------------------------------------------------------------------------- |
| 🔵 blue | Crates (i.e. their implicit root module) |
| 🟢 green | Items visible to all and everything (i.e. pub) |
| 🟡 yellow | Items visible to the current crate (i.e. pub(crate)) |
| 🟠 orange | Items visible to a certain parent module (i.e. pub(in path)) |
| 🔴 red | Items visible to the current module (i.e. pub(self), implied by lack of pub …) |
| 🟣 purple | Orphaned modules (i.e. a file exists on disk but no corresponding mod …) |
cargo-modules's generate graph command checks for the presence of a --acyclic flag. If found it will search for cycles in the directed graph and return an error for any cycles it found.
Running cargo modules generate graph --lib --acyclic on the source of the tool itself emits the following cycle error:
``plain
Error: Circular dependency betweencargomodules::options::generalandcargomodules::options::generate`.
┌> cargomodules::options::general │ └─> cargomodules::options::generate::graph │ └─> cargo_modules::options::generate └──────────┘ ```
cargo-modules checks for the presence of a NO_COLOR environment variable that, when present (regardless of its value), prevents the addition of color to the console output.
Please read CONTRIBUTING.md for details on our code of conduct,
and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is licensed under the MPL-2.0 – see the LICENSE.md file for details.