cargo-local 0.4.0

A third-party cargo extension that lists local source locations of dependencies
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

*Note: The original codebase was taken from the [`cargo open`](https://github.com/carols10cents/cargo-open) project, and was adapted to work for listing source files instead.*

# `cargo local`

A third-party cargo extension that lists local source locations of dependencies.

## Installing

You can install the tool from crates.io by running:

``` bash
$ cargo install cargo-local
```

This will install the executable `cargo-local` in your cargo `bin` directory, which on *nix systems would be `~/.cargo/bin`. You should add that directory to your `PATH`.

## Usage

After installing, you should be able to go to any cargo project's root directory and run the following command:

``` bash
$ cargo local
```

This will output a list of all of the dependencies' source locations, or at least the ones that exist in the filesystem. If you provide a list of package names, the tool will show the location of only those. Example output:

``` bash
$ cargo local clap cargo
/home/andrew/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/clap-4.5.30
/home/andrew/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/cargo-0.86.0
```

You can run the command with `--only-names` to list package names alone -- useful for generating shell completion, for instance:

``` bash
$ cargo local --only-names
autocfg
gix-packetline
tar
equivalent
wasm-bindgen-backend
...
```

On its own, this isn't super interesting, but it can be used as a component in other tools like shell scripts. A few examples follow:

### cargo-open

The project that this codebase was more-or-less copied from can be more-or-less implemented like so:

``` bash
$ $EDITOR `cargo local <package-name>`
```

A longer script that handles errors might look like this:

``` bash
#! /bin/sh

if [ $# -lt 2 ]; then
  echo "USAGE: cargo open <package-name>"
  exit 1
fi

_subcommand=$1 # ignore the "open" subcommand
package=$2
path=$(cargo local $package)
status=$?
if [ $status -ne 0 ]; then
  exit $status
fi

$EDITOR "$path"
```

### cargo-tags

The original plan for this fork. A tool like this already exists as [rusty-tags](https://github.com/dan-t/rusty-tags), but it's easy to do something similar with a one-liner: `ctags -o Cargo.tags -R $(cargo local)`. A longer script with error handling:

``` bash
#! /bin/sh

sources=$(cargo local)
status=$?
if [ $status -ne 0 ]; then
  exit $status
fi

echo "$sources" | xargs --delimiter="\n" ctags -o Cargo.tags -R
```

## Contributing

You can run the tool locally by executing `cargo run local`. Note the subcommand -- it's necessary, because it would ordinarily be called as `cargo local`.

If you'd like to run it on a different directory, you can either install the local program with `cargo install --path .`, or you can find the compiled binary in `target/debug/cargo-local`, and run it by using the full path to the executable.