/cargo-modules

Render your crate's module/item structure as a tree or graph

Primary LanguageRustMozilla Public License 2.0MPL-2.0

cargo-modules

Build Status Downloads Version License

Synopsis

A cargo plugin for showing an overview of a crate's modules.

Motivation

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:

Installation

Install cargo-modules via:

cargo install cargo-modules

Usage

Print crate as a tree

cargo modules generate tree <OPTIONS>
USAGE:
    cargo-modules generate tree [FLAGS] [OPTIONS]

FLAGS:
        --all-features           Activate all available features
        --cfg-test               Analyze with `#[cfg(test)]` enabled
    -h, --help                   Prints help information
        --lib                    Process only this package's library
        --no-default-features    Do not activate the `default` feature
    -V, --version                Prints version information
        --verbose                Use verbose output
        --with-fns               Include functions (e.g. fns, async fns, const fns)
        --with-orphans           Include orphaned modules (i.e. unused files in /src)
        --with-sysroot           Include sysroot crates (`std`, `core` & friends) in analysis
        --with-tests             Include tests (e.g. `#[test] fn …`)
        --with-traits            Include traits (e.g. trait, unsafe trait)
        --with-types             Include types (e.g. structs, unions, enums)

OPTIONS:
        --bin <bin>                        Process only the specified binary
        --features <features>...           List of features to activate. This will be ignored if `--cargo-all-features`
                                           is provided
        --focus-on <focus-on>              Focus the graph on a particular path or use-tree's environment, e.g.
                                           "foo:bar::{self, baz, blee::*}"
        --manifest-path <manifest-path>    Path to Cargo.toml [default: .]
        --max-depth <max-depth>            The maximum depth of the generated graph relative to the crate's root node,
                                           or nodes selected by '--focus-on'
    -p, --package <package>                Package to process (see `cargo help pkgid`)
        --target <target>                  Analyze for target triple

The following image is the result of using the following command to generate a tree of the smoke test project within its own repo:

cd ./tests/projects/smoke
cargo-modules generate tree --with-types --with-tests --with-orphans

Output of cargo modules generate tree …

Line Structure

The individual lines are structured as follows:

└── <keyword> <name>: <visibility> <test-attributes>

Line Colors

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 …)

Print crate as a graph

cargo modules generate graph <OPTIONS>
USAGE:
    cargo-modules generate graph [FLAGS] [OPTIONS]

FLAGS:
        --all-features           Activate all available features
        --cfg-test               Analyze with `#[cfg(test)]` enabled
    -h, --help                   Prints help information
        --lib                    Process only this package's library
        --no-default-features    Do not activate the `default` feature
    -V, --version                Prints version information
        --verbose                Use verbose output
        --with-externs           Include used modules and types from extern crates
        --with-fns               Include functions (e.g. fns, async fns, const fns)
        --with-orphans           Include orphaned modules (i.e. unused files in /src)
        --with-sysroot           Include sysroot crates (`std`, `core` & friends) in analysis
        --with-tests             Include tests (e.g. `#[test] fn …`)
        --with-traits            Include traits (e.g. trait, unsafe trait)
        --with-types             Include types (e.g. structs, unions, enums)
        --with-uses              Include used modules and types

OPTIONS:
        --bin <bin>                        Process only the specified binary
        --features <features>...           List of features to activate. This will be ignored if `--cargo-all-features`
                                           is provided
        --focus-on <focus-on>              Focus the graph on a particular path or use-tree's environment, e.g.
                                           "foo:bar::{self, baz, blee::*}"
        --layout <layout>                  The graph layout algorithm to use (e.g. dot, neato, twopi, circo, fdp, sfdp)
                                           [default: neato]
        --manifest-path <manifest-path>    Path to Cargo.toml [default: .]
        --max-depth <max-depth>            The maximum depth of the generated graph relative to the crate's root node,
                                           or nodes selected by '--focus-on'
    -p, --package <package>                Package to process (see `cargo help pkgid`)
        --target <target>                  Analyze for target triple


        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:

cd ./tests/projects/smoke
cargo-modules generate graph --with-types --with-tests --with-orphans | dot -Tsvg

Output of cargo modules generate graph …

Node Structure

The individual nodes are structured as follows:

┌────────────────────────┐
│ <visibility> <keyword> │
├────────────────────────┤
│         <path>         │
└────────────────────────┘

Node Colors

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 …)

No-Color Mode

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.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct,
and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MPL-2.0 – see the LICENSE.md file for details.