cargo-deps 1.5.1

Cargo subcommand for building dependency graphs of Rust projects.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

# cargo-deps

[![Build Status](https://img.shields.io/github/actions/workflow/status/mrcnski/cargo-deps/ci.yml?style=flat-square)](https://github.com/mrcnski/cargo-deps/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/cargo-deps.svg)](https://crates.io/crates/cargo-deps)
[![Documentation](https://docs.rs/cargo-deps/badge.svg)](https://docs.rs/cargo-deps)
[![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
[![Downloads](https://img.shields.io/crates/d/cargo-deps.svg)](https://crates.io/crates/cargo-deps)
[![Issues](https://img.shields.io/github/issues-raw/mrcnski/cargo-deps.svg)](https://github.com/mrcnski/cargo-deps/issues)
[![LoC](https://tokei.rs/b1/github/mrcnski/cargo-deps)](https://github.com/mrcnski/cargo-deps)
[![Coverage Status](https://coveralls.io/repos/github/mrcnski/cargo-deps/badge.svg?branch=master)](https://coveralls.io/github/mrcnski/cargo-deps?branch=master)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](https://opensource.org/license/bsd-3-clause/)

**Note:** This crate is not actively worked on. Consider using one of the crates mentioned in [Alternatives](#alternatives).

<details>
<summary>Table of Contents</summary>
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**

- [cargo-deps](#cargo-deps)
    - [About](#about)
    - [Installing](#installing)
    - [Instructions](#instructions)
        - [Dependency Kinds](#dependency-kinds)
        - [Filtering](#filtering)
            - [Excluding](#excluding)
            - [Depth](#depth)
            - [Filtering transitive edges](#filtering-transitive-edges)
        - [Subgraphs](#subgraphs)
        - [Examples](#examples)
        - [More info](#more-info)
    - [Alternatives](#alternatives)
    - [License](#license)
    - [Dependencies](#dependencies)
    - [Changelog](#changelog)

<!-- markdown-toc end -->
</details>

## About

Cargo subcommand for building dependency graphs of Rust projects.

This project is an improvement on the unmaintained and buggy [cargo-graph](https://github.com/kbknapp/cargo-graph).

**Example:**

![safe_app dependencies](safe-client-libs.png)

## Installing

`cargo-deps` can be installed with `cargo install`:

```
cargo install cargo-deps
```

## Instructions

First, make sure you have [graphviz](https://graphviz.gitlab.io/download/) installed.

Next, just `cd` into the Rust project directory you want to graph and run:

```
cargo deps | dot -Tpng > graph.png
```

That's it! `graph.png` will contain the graph (you can change its name, of course!)

Note that `>` may not work if the output file already exists, in which case you can try `>|`.

### Dependency Kinds

The default behavior is to exclude optional, dev, and build dependencies. To see all dependencies, pass `--all-deps`:

```
cargo deps --all-deps | dot -Tpng > graph.png
```

Dependencies are colored depending on their kind:

* **Black:** regular dependency
* **Purple:** build dependency
* **Blue:** dev dependency
* **Red:** optional dependency

A dependency can be of more than one kind. In such cases, it is colored with the following priority:

```
Regular -> Build -> Dev -> Optional
```

For example, if a dependency is both a build and a dev dependency, then it will be colored as a build dependency. If, however, you pass the `--dev-deps` option instead of `--all-deps`, the dependency will be colored as a dev dependency (as the build-dependency graph will not be shown).

### Filtering

Some Rust projects have really big dependency trees and maybe you just want to display certain dependencies, like the ones in the same workspace. Fortunately, `cargo-deps` provides the `--filter` option for this use case. Unfortunately, you have to explicitly list all the dependencies you want to keep, and `cargo-deps` doesn't detect workspaces just yet.

#### Excluding

It can be useful to exclude certain crates from the final graph. This can be achieved with the `--exclude` flag taking the undesired crates as arguments.

#### Depth

In order to constrain the size of graphs and make them cleaner, it is possible to limit the output to dependencies within a certain depth using the `--depth` option.

#### Filtering transitive edges

For large dependency graphs, the `--no-transitive-deps` option can be used to filter out edges that are "covered" by a transitive dependency, which can make visual parsing a little easier by omitting some redundant edges. For example, if crate `A` depends directly on crate `B` and `C`, and crate `B` depends directly on crate `C`, this option would omit the edge from `A` to `C`. To illustrate, compare the [default dependency graph](tokei-default.png) for Tokei, generated by `cargo deps`, to the [graph with transitive edges removed](tokei-transitive.png), generated by `cargo deps --no-transitive-deps`.

### Subgraphs

You can visually group a set of dependencies by using the `--subgraph` command.

### Examples

**[Tokei](https://github.com/Aaronepower/tokei)** -- [graph](tokei.png)

This was generated using the command:

```
cargo deps -I --all-deps --no-regular-deps | dot -Tpng > tokei.png
```

**[SAFE Client Libs](https://github.com/maidsafe/safe_client_libs)** -- [graph](safe-client-libs.png)

This was generated using the following whopper of a command to display only MaidSafe dependencies:

```
cargo deps --all-deps --include-orphans --subgraph safe_app safe_app_jni safe_authenticator safe_authenticator_jni safe_core --subgraph-name "SAFE Client Libs" --filter accumulator config_file_handler crust ffi_utils fake_clock lru_time_cache maidsafe_utilities parsec resource_proof routing rust_sodium safe_app safe_app_jni safe_authenticator safe_authenticator_jni safe_bindgen safe_core safe_crypto safe_vault secure_serialisation self_encryption system_uri tokio_utp --manifest-path safe_app/Cargo.toml | dot -Tpng -Nfontname=Iosevka -Gfontname=Iosevka > safe-client-libs.png
```

### More info

Run `cargo deps -h` to see all available options.

## Alternatives

While `cargo-deps` should work for most use cases, it has an outdated architecture and the creator is not working on active development. Some alternatives to consider are:

- [`cargo-depgraph`](https://sr.ht/~jplatte/cargo-depgraph/): Has more features than `cargo-deps`.
- [`cargo-tree`](https://doc.rust-lang.org/cargo/commands/cargo-tree.html): Displays dependencies in a textual format. As of Rust 1.44 is included in `cargo` as a subcommand.

## Dependencies

![cargo-deps dependencies](cargo-deps.png)

## Changelog

[Changelog](CHANGELOG.md)