{"id":13547180,"url":"https://github.com/regexident/cargo-modules","last_synced_at":"2025-04-13T20:17:31.053Z","repository":{"id":9383886,"uuid":"61953522","full_name":"regexident/cargo-modules","owner":"regexident","description":"Visualize/analyze a Rust crate's internal structure","archived":false,"fork":false,"pushed_at":"2025-04-10T14:48:11.000Z","size":4655,"stargazers_count":1082,"open_issues_count":15,"forks_count":53,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-13T20:17:20.658Z","etag":null,"topics":["cargo-commands","code-analysis-tool","developer-tools","rust","rust-tools","tooling"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/regexident.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-06-25T17:13:52.000Z","updated_at":"2025-04-10T02:57:36.000Z","dependencies_parsed_at":"2023-02-18T19:31:18.207Z","dependency_job_id":"c264afdd-7fb5-4138-96b0-01375538e30a","html_url":"https://github.com/regexident/cargo-modules","commit_stats":{"total_commits":419,"total_committers":19,"mean_commits":22.05263157894737,"dds":"0.38186157517899766","last_synced_commit":"fbc8d1759b459f9f1911d92e85bc573223587f58"},"previous_names":[],"tags_count":154,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regexident%2Fcargo-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regexident%2Fcargo-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regexident%2Fcargo-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regexident%2Fcargo-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/regexident","download_url":"https://codeload.github.com/regexident/cargo-modules/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248774961,"owners_count":21159534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cargo-commands","code-analysis-tool","developer-tools","rust","rust-tools","tooling"],"created_at":"2024-08-01T12:00:52.129Z","updated_at":"2025-04-13T20:17:31.014Z","avatar_url":"https://github.com/regexident.png","language":"Rust","funding_links":[],"categories":["Rust","Development tools"],"sub_categories":["Build system"],"readme":"# cargo-modules\n\n[![Downloads](https://img.shields.io/crates/d/cargo-modules.svg?style=flat-square)](https://crates.io/crates/cargo-modules/)\n[![Version](https://img.shields.io/crates/v/cargo-modules.svg?style=flat-square)](https://crates.io/crates/cargo-modules/)\n[![License](https://img.shields.io/crates/l/cargo-modules.svg?style=flat-square)](https://crates.io/crates/cargo-modules/)\n\n## Synopsis\n\nA cargo plugin for visualizing/analyzing a crate's internal structure.\n\n## Motivation\n\nWith time, as your Rust projects grow bigger and bigger, it gets more and more important to properly structure your code.\nFortunately 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.\nWhile 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.\n\nThis is where `cargo-modules` comes into play:\n\n## Installation\n\nInstall `cargo-modules` via:\n\n```bash\ncargo install cargo-modules\n```\n\n## Usage\n\nThe `cargo-modules` tool comes with a couple of commands:\n\n```bash\n# Print a crate's hierarchical structure as a tree:\ncargo modules structure \u003cOPTIONS\u003e\n\n# Print a crate's internal dependencies as a graph:\ncargo modules dependencies \u003cOPTIONS\u003e\n\n# Detect unlinked source files within a crate's directory:\ncargo modules orphans \u003cOPTIONS\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand help\u003c/summary\u003e\n\n```terminal\n$ cargo modules --help\n\nVisualize/analyze a crate's internal structure.\n\nUsage: cargo-modules \u003cCOMMAND\u003e\n\nCommands:\n  structure     Prints a crate's hierarchical structure as a tree.\n  dependencies  Prints a crate's internal dependencies as a graph.\n  orphans       Detects unlinked source files within a crate's directory.\n  help          Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help  Print help\n```\n\n\u003c/details\u003e\n\n### cargo modules structure\n\nPrint a crate's hierarchical structure as a tree:\n\n```bash\ncargo modules structure \u003cOPTIONS\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand help\u003c/summary\u003e\n\n```terminal\n$ cargo modules structure --help\n\nPrints a crate's hierarchical structure as a tree.\n\nUsage: cargo-modules structure [OPTIONS]\n\nOptions:\n      --verbose                        Use verbose output\n      --lib                            Process only this package's library\n      --bin \u003cBIN\u003e                      Process only the specified binary\n  -p, --package \u003cPACKAGE\u003e              Package to process (see `cargo help pkgid`)\n      --no-default-features            Do not activate the `default` feature\n      --all-features                   Activate all available features\n      --features \u003cFEATURES\u003e            List of features to activate. This will be ignored if `--cargo-all-features` is provided\n      --target \u003cTARGET\u003e                Analyze for target triple\n      --manifest-path \u003cMANIFEST_PATH\u003e  Path to Cargo.toml [default: .]\n      --no-fns                         Filter out functions (e.g. fns, async fns, const fns) from tree\n      --no-traits                      Filter out traits (e.g. trait, unsafe trait) from tree\n      --no-types                       Filter out types (e.g. structs, unions, enums) from tree\n      --sort-by \u003cSORT_BY\u003e              The sorting order to use (e.g. name, visibility, kind) [default: name]\n      --sort-reversed                  Reverses the sorting order\n      --focus-on \u003cFOCUS_ON\u003e            Focus the graph on a particular path or use-tree's environment, e.g. \"foo::bar::{self, baz, blee::*}\"\n      --max-depth \u003cMAX_DEPTH\u003e          The maximum depth of the generated graph relative to the crate's root node, or nodes selected by '--focus-on'\n      --cfg-test                       Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)\n  -h, --help                           Print help\n```\n\n\u003c/details\u003e\n\n#### Example: Modules Structure as Text Tree\n\n```bash\ncd ./tests/projects/readme_tree_example\ncargo-modules structure --cfg-test\n```\n\nOutput:\n\n![Output of `cargo modules structure …`](docs/structure_output.png)\n\n```rust\ncrate readme_tree_example\n├── trait Lorem: pub\n├── mod amet: pub(crate)\n│   └── mod consectetur: pub(self)\n│       └── mod adipiscing: pub(self)\n│           └── union Elit: pub(in crate::amet)\n├── mod dolor: pub(crate)\n│   └── enum Sit: pub(crate)\n└── mod tests: pub(crate) #[cfg(test)]\n    └── fn it_works: pub(self) #[test]\n```\n\n(Project source code: [readme_tree_example/src/lib.rs](./tests/projects/readme_tree_example/src/lib.rs))\n\n#### Terminal Colors\n\nIf you are running the command on a terminal with color support and don't have `NO_COLOR` defined in your environment, then the output will be colored for easier visual parsing:\n\n```plain\n└── \u003cvisibility\u003e \u003ckeyword\u003e \u003cname\u003e [\u003ctest-attributes\u003e]\n```\n\nThe `\u003cvisibility\u003e` ([more info](https://doc.rust-lang.org/reference/visibility-and-privacy.html)) is furthermore highlighted by the following colors:\n\n| Color    | Meaning                                                                            |\n| -------- | ---------------------------------------------------------------------------------- |\n| 🟢 green  | Items visible to all and everything (i.e. `pub`)                                   |\n| 🟡 yellow | Items visible to the current crate (i.e. `pub(crate)`)                             |\n| 🟠 orange | Items visible to a certain parent module (i.e. `pub(in path)`)                     |\n| 🔴 red    | Items visible to the current module (i.e. `pub(self)`, implied by lack of `pub …`) |\n\nThe `\u003ckeyword\u003e` is highlighted in 🔵 blue to visually separate it from the name.\n\nTest-guarded items (i.e. `#[cfg(test)] …`) and test functions (i.e. `#[test] fn …`) have their corresponding `\u003ctest-attributes\u003e` printed next to them in gray and cyan.\n\n### cargo modules dependencies\n\nPrint a crate's internal dependencies as a graph:\n\n```bash\ncargo modules dependencies \u003cOPTIONS\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand help\u003c/summary\u003e\n\n```terminal\n$ cargo modules dependencies --help\n\nPrints a crate's internal dependencies as a graph.\n\nUsage: cargo-modules dependencies [OPTIONS]\n\nOptions:\n      --verbose                        Use verbose output\n      --lib                            Process only this package's library\n      --bin \u003cBIN\u003e                      Process only the specified binary\n  -p, --package \u003cPACKAGE\u003e              Package to process (see `cargo help pkgid`)\n      --no-default-features            Do not activate the `default` feature\n      --all-features                   Activate all available features\n      --features \u003cFEATURES\u003e            List of features to activate. This will be ignored if `--cargo-all-features` is provided\n      --target \u003cTARGET\u003e                Analyze for target triple\n      --manifest-path \u003cMANIFEST_PATH\u003e  Path to Cargo.toml [default: .]\n      --no-externs                     Filter out extern items from extern crates from graph\n      --no-fns                         Filter out functions (e.g. fns, async fns, const fns) from graph\n      --no-modules                     Filter out modules (e.g. `mod foo`, `mod foo {}`) from graph\n      --no-sysroot                     Filter out sysroot crates (`std`, `core` \u0026 friends) from graph\n      --no-traits                      Filter out traits (e.g. trait, unsafe trait) from graph\n      --no-types                       Filter out types (e.g. structs, unions, enums) from graph\n      --no-uses                        Filter out \"use\" edges from graph\n      --acyclic                        Require graph to be acyclic\n      --layout \u003cLAYOUT\u003e                The graph layout algorithm to use (e.g. none, dot, neato, twopi, circo, fdp, sfdp) [default: neato]\n      --focus-on \u003cFOCUS_ON\u003e            Focus the graph on a particular path or use-tree's environment, e.g. \"foo::bar::{self, baz, blee::*}\"\n      --max-depth \u003cMAX_DEPTH\u003e          The maximum depth of the generated graph relative to the crate's root node, or nodes selected by '--focus-on'\n      --cfg-test                       Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)\n  -h, --help                           Print help\n\n\n        If you have xdot installed on your system, you can run this using:\n        `cargo modules dependencies | xdot -`\n```\n\n\u003c/details\u003e\n\n#### Example: Graphical Module Structure\n\n```bash\ncargo modules dependencies --no-externs --no-fns --no-sysroot --no-traits --no-types --no-uses \u003e mods.dot\n```\n\n(The command above is equivalent to `cargo-modules generate graph` from v0.12.0 or earlier.)\n\n![Output of `cargo modules dependencies …`](docs/dependencies_mods_only_output.svg)\n\n#### Example: Graphical Dependencies\n\n```bash\ncd ./tests/projects/smoke\ncargo-modules dependencies --cfg-test | dot -Tsvg\n```\n\n![Output of `cargo modules dependencies …`](docs/dependencies_output.svg)\n\n```plain\nSee \"./docs/dependencies_output.dot\" for the corresponding raw dot file.\n```\n\n(Project source code: [readme_graph_example/src/lib.rs](./tests/projects/readme_graph_example/src/lib.rs))\n\n#### Node Structure\n\nThe individual nodes are structured as follows:\n\n```plain\n┌────────────────────────┐\n│ \u003cvisibility\u003e \u003ckeyword\u003e │\n├────────────────────────┤\n│         \u003cpath\u003e         │\n└────────────────────────┘\n```\n\n#### Node Colors\n\nThe `\u003cvisibility\u003e` ([more info](https://doc.rust-lang.org/reference/visibility-and-privacy.html)) is furthermore highlighted by the following colors:\n\n| Color    | Meaning                                                                            |\n| -------- | ---------------------------------------------------------------------------------- |\n| 🔵 blue   | Crates (i.e. their implicit root module)                                           |\n| 🟢 green  | Items visible to all and everything (i.e. `pub`)                                   |\n| 🟡 yellow | Items visible to the current crate (i.e. `pub(crate)`)                             |\n| 🟠 orange | Items visible to a certain parent module (i.e. `pub(in path)`)                     |\n| 🔴 red    | Items visible to the current module (i.e. `pub(self)`, implied by lack of `pub …`) |\n\n#### Acyclic Mode\n\ncargo-modules's `dependencies` 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.\n\nRunning `cargo modules dependencies --lib --acyclic` on the source of the tool itself emits the following cycle error:\n\n```plain\nError: Circular dependency between `cargo_modules::options::general` and `cargo_modules::options::generate`.\n\n┌\u003e cargo_modules::options::general\n│  └─\u003e cargo_modules::options::generate::graph\n│      └─\u003e cargo_modules::options::generate\n└──────────┘\n```\n\n### cargo modules orphans\n\nDetect unlinked source files within a crate's directory:\n\n```bash\ncargo modules orphans \u003cOPTIONS\u003e\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eCommand help\u003c/summary\u003e\n\n```terminal\n$ cargo modules orphans --help\n\nDetects unlinked source files within a crate's directory.\n\nUsage: cargo-modules orphans [OPTIONS]\n\nOptions:\n      --verbose                        Use verbose output\n      --lib                            Process only this package's library\n      --bin \u003cBIN\u003e                      Process only the specified binary\n  -p, --package \u003cPACKAGE\u003e              Package to process (see `cargo help pkgid`)\n      --no-default-features            Do not activate the `default` feature\n      --all-features                   Activate all available features\n      --features \u003cFEATURES\u003e            List of features to activate. This will be ignored if `--cargo-all-features` is provided\n      --target \u003cTARGET\u003e                Analyze for target triple\n      --manifest-path \u003cMANIFEST_PATH\u003e  Path to Cargo.toml [default: .]\n      --deny                           Returns a failure code if one or more orphans are found\n      --cfg-test                       Analyze with `#[cfg(test)]` enabled (i.e as if built via `cargo test`)\n  -h, --help                           Print help\n```\n\n\u003c/details\u003e\n\n#### Example\n\n```bash\ncd ./tests/projects/readme_tree_example\ncargo-modules structure --types --traits --fns --tests\n```\n\nOutput:\n\n![Output of `cargo modules structure …`](docs/orphans_output.png)\n\n```plain\n2 orphans found:\n\nwarning: orphaned module `foo` at src/orphans/foo/mod.rs\n  --\u003e src/orphans.rs\n   |  ^^^^^^^^^^^^^^ orphan module not loaded from file\n   |\n help: consider loading `foo` from module `orphans::orphans`\n   |\n   |  mod foo;\n   |  ++++++++\n   |\n\nwarning: orphaned module `bar` at src/orphans/bar.rs\n  --\u003e src/orphans.rs\n   |  ^^^^^^^^^^^^^^ orphan module not loaded from file\n   |\n help: consider loading `bar` from module `orphans::orphans`\n   |\n   |  mod bar;\n   |  ++++++++\n   |\n\nError: Found 2 orphans in crate 'orphans'\n```\n\n(Project source code: [readme_tree_example/src/lib.rs](./tests/projects/readme_orphans_example/src/lib.rs))\n\n### No-Color Mode\n\ncargo-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 (and only the console output!).\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our [code of conduct](https://www.rust-lang.org/conduct.html),  \nand the process for submitting pull requests to us.\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/regexident/cargo-modules/tags).\n\n## License\n\nThis project is licensed under the [**MPL-2.0**](https://www.tldrlegal.com/l/mpl-2.0) – see the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregexident%2Fcargo-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fregexident%2Fcargo-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregexident%2Fcargo-modules/lists"}