rusty-tags 0.3.5

Create ctags/etags for a cargo project and all of its 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
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

[![Build Status](https://travis-ci.org/dan-t/rusty-tags.svg?branch=master)](https://travis-ci.org/dan-t/rusty-tags)

rusty-tags
==========

A command line tool that creates tags - for source code navigation by
using [ctags](<http://ctags.sourceforge.net>) - for a cargo project and all
of its dependencies.

Prerequisites
=============

* [ctags](<http://ctags.sourceforge.net>) installed
* [git](<http://git-scm.com/>) installed if git dependencies are used

Installation
============

* get `rustc` and `cargo` from [here](<http://www.rust-lang.org/install.html>)
* `git clone https://github.com/dan-t/rusty-tags.git`
* `cd rusty-tags`
* `cargo build --release`

(Last successful build with: rustc 1.0.0-beta.5 (7b4ef47b7 2015-05-11))

The build binary will be located at `target/release/rusty-tags`.

Usage
=====

`cargo build` has to be called at least once, to download the source code of
the dependencies. If a dependency gets added or updated, then most likely
`cargo build` has to be called again.

Just calling `rusty-tags vi` then anywhere inside of a cargo project should
just work and after its run a `rusty-tags.vi` file should be beside
of the `Cargo.toml` file.

`rusty-tags` will also put a `rusty-tags.vi` to the source code of
every dependency, so after jumping to a dependency, you're able
to jump further to its dependencies.

`rusty-tags` should also correctly handle the case if a dependency
reexports parts of its own dependencies.

Currently `rusty-tags` doesn't support local dependencies and dependency overwrites.
For git dependencies it only searches inside of `~/.cargo/git/checkouts/` and for
crates.io dependencies inside of `~/.cargo/registry/src/github.com-*`.

Rust Standard Library Support
=============================

The source code of Rust already contains a script for creating tags, but
if you only want to jump into the standard library then reducing the directories
gives better results.

First get the Rust source code:

    $ git clone https://github.com/rust-lang/rust.git
    $ cd rust

And now execute the following script inside of the rust directory:

    #!/usr/bin/env bash
    
    src_dirs=`ls -d $PWD/src/{liballoc,libarena,libbacktrace,libcollections,libcore,libflate,libfmt_macros,libgetopts,libgraphviz,liblog,librand,librbml,libserialize,libstd,libsyntax,libterm}`
    
    ctags -f rusty-tags.vi --options=src/etc/ctags.rust --languages=Rust --recurse $src_dirs
    
    ctags -e -f rusty-tags.emacs --options=src/etc/ctags.rust --languages=Rust --recurse $src_dirs

You can now add this tags file manually to your list of tags files in your editor settings
or you can copy the `rusty-tags.vi` and `rusty-tags.emacs` files to `~/.rusty-tags/rust-std-lib.vi`
respectively `~/.rusty-tags/rust-std-lib.emacs`. Then `rusty-tags` will automatically add
the standard library tags file to every tags file it creates.

The automatic adding might be a bit annoying if you reguarly update the rust compiler
and if the standard library changes. So adding the tags file manually might be the
better option and also speeds up the creation of the tags.

Vim Configuration
=================

Put this into your `~/.vim/after/ftplugin/rust.vim` file:

    set tags=rusty-tags.vi;/
    autocmd BufWrite *.rs :silent !rusty-tags vi

or, if you want to manually add the tags for the rust standard library:

    set tags=rusty-tags.vi;/,path-to-rust-source-code/rusty-tags.vi
    autocmd BufWrite *.rs :silent !rusty-tags vi

The first line (only supported by vim >= 7.4) ensures that vim will
automatically search for a `rusty-tags.vi` file upwards the directory hierarchy.

This tags setting is important if you want to jump to dependencies and
then further jump to theirs dependencies.

The second line ensures that your projects tag file gets updated if a file is written.

Normally you want to call the `rusty-tags` command in the backgroud by adding a `&`:

    autocmd BufWrite *.rs :silent !rusty-tags vi &

But I had sometimes strange behaviours this way that I couldn't track down
until now. So you can try using it with the `&`, and if it doesn't work,
if the tags aren't correctly updated, then you know the reason.

Emacs Support
=============

There's now a first version with emacs support.

Replace every occurrence of `vi` with `emacs` in the README e.g.:
* `rusty-tags vi` => `rusty-tags emacs`
* `make TAGS.vi` => `make TAGS.emacs`
* `rusty-tags.vi` => `rusty-tags.emacs`

Instead of merging the tags files like in the vi case, an `include`
line is added to the emacs tags file which includes the tags files
of the dependencies.

I haven't tested the emacs tags, so some feedback would be nice!