Re: [Valgrind-users] --tool help not too helpful

[Philippe W. <phi...@sk...>]

On Wed, 2014-04-30 at 15:27 +0000, Skip Montanaro wrote:
> I went to file a bug report but was thwarted by the need to create yet
> another login to file a simple bug, and find Bugzilla an almost
> insurmountable hurdle anyway, so I will just mention my issues and
> suggestions here, and hope someone better tied into Valgrind development
> will pass it along. (That said, as a former Python core developer, I
> realize the need/desire for login credentials.)
> 
> I am a brand new Valgrind user, afflicted with some threading problems. I
> knew about the "memcheck" tool, but didn't know what any of the other
> tools were. While reading the man page, I saw mention of the Helgrind and
> DRD tools. "Great!" I thought. Alas, specifying "--tool=Helgrind" or
> "--tool=DRD" on the command line resulted in rather vague error:
> 
> ... failed to start tool '<whatever>' for platform 'amd64-linux': ...
> 
> Initially, I thought those tools were simply not available on my
> platform. Eventually, though, I figured out that tool names must be given
> in lower case. "Helgrind" and "DRD" appear to only be given with those
> spellings. I saw one instance of "helgrind" in the man page, but it was
> part of a larger compound word. I saw no mention of "drd".
> 
> Further, I saw no enumeration of all the available tools. The --help
> output says that "memcheck" is the default tool. Any mention in --help
> output of other tools was secondary (mentioning tools which support
> various options).
> 
> So, my recommendations:
> 
> 1. Briefly enumerate all the possible tools somewhere, together in one
> place. This would be great in the man page. I think it would be less
> important in the --help output.
In the next valgrind version, the man page (and the corresponding place
in the user manual) will now be:

  ...
  TOOL SELECTION OPTIONS
       The single most important option.

       --tool=<toolname> [default: memcheck]
           Run the Valgrind tool called toolname, e.g. memcheck, cachegrind, callgrind,
           helgrind, drd, massif, lackey, none, exp-sgcheck, exp-bbv, exp-dhat, etc.
   ...

That being said, I stronly suggest to read the user manual, in
particular for helgrind and drd : race detection is a sophisticated
functionality, and the helgrind and drd sections are very useful
to read.

And, cherry on the cake, all user manual tool sections starts with
a sentence such as:

  ...
  To use this tool, you must specify --tool=helgrind on the Valgrind command line.
  ...

which I guess would have helped :)

Philippe