[Valgrind-users] RFC: proposal to remove user annotation from `cg_annotate`

[Nicholas N. <n.n...@gm...>]

Hi,

I recently rewrote `cg_annotate`, `cg_diff`, and `cg_merge` in Python. The
old versions were written in Perl, Perl, and C, respectively. The new
versions are much nicer and easier to modify, and I have various ideas for
improving `cg_annotate`. This email is about one of those ideas.

A typical way to invoke `cg_annotate` is like this:

> cg_annotate cachegrind.out.12345

This implies `--auto=yes`, which requests line-by-line "auto-annotation" of
source files. I.e. `cg_annotate` will automatically annotate all files in
the profile that meet the significance threshold.

It's also possible to do something like this:

> cg_annotate --auto=no cachegrind.out.12345 a.c b.c

Which instead requests "user annotation" of the files `a.c` and `b.c`.

My thesis is that auto-annotation suffices in practice for all reasonable
use cases, and that user annotation is unnecessary and can be removed.

When I first wrote `cg_annotate` in 2002, only user annotation was
implemented. Shortly after, I added the `--auto={yes,no}` option. Since
then I've never used user annotation, and I suspect nobody else has either.
User annotation is ok when dealing with tiny programs, but as soon as you
are profiling a program with more than a handful of source files it becomes
impractical.

The only possible use cases I can think of for user annotation are as
follows.

   - If you want to see a particular file(s) annotated but you don't want
   to see any others, then you can use user annotation in combination with
   `--auto=no`. But it's trivial to search through the output for the
   particular file, so this doesn't seem important.
   - If the path to a file is somehow really messed up in the debug info,
   it might be possible that auto-annotation would fail to find it, but user
   annotation could find it, possibly in combination with `-I`. But this seems
   unlikely. Some basic testing shows that gcc, clang and rustc all default to
   using full paths in debug info. gcc supports `-fdebug-prefix-map` but that
   seems to mostly be used for changing full paths to relative paths, which
   will still work fine.

Removing user annotation would (a) simplify the code and docs, and (b)
enable the possibility of moving the merge functionality from `cg_merge`
into `cg_annotate`, by allowing the user to specify multiple cachegrind.out
files as input.

So: is anybody using user annotation? Does anybody see any problems with
this proposal?

Thanks.

Nick