flogtool doesn't get automatically provided

[zooko]

Wolfgang Strobl built tahoe-lafs per source:docs/quickstart.rst, and later, because source:docs/logging.rst​ had told him to, wanted to run flogtool. He was frustrated that there was no documentation explaining how to get a working flogtool script, and that the thing named ./support/bin/flogtool that he found gave an exception when executed:

​https://tahoe-lafs.org/pipermail/tahoe-dev/2012-March/007159.html

To close this ticket, extend source:docs/logging.rst​ to explain how to get flogtool running, and possibly also extend the build system somehow so that it makes it easier to get a working flogtool script.

[zooko]

See ​https://tahoe-lafs.org/pipermail/tahoe-dev/2012-March/007162.html for my ideas about this.

[david-sarah@…]

In 922ed08c25a1a142:

Document PYTHONPATH problem when running flogtool. refs #1693

[davidsarah]

Add 'tahoe debug flogtool' command, test for --help, and docs. This version gets the help synopses more correct, and changes the doc to say that this command is added in 1.10.0 rather than 1.9.2. fixes #1693

[warner]

The patch looks good, and I'm landing it. One quibble about the docs it's modifying, though: the specific PYTHONPATH issue is when Foolscap was only installed as part of Tahoe, and therefore bin/foolscap wasn't available from outside the tahoe tree's copy. The exception cited in the original report looks like it was a pkg_resources problem (probably because pkg_resources was only installed as part of Tahoe). My quibble is that I want to avoid giving the impression that tahoe itself has to be on PYTHONPATH to use 'flogtool' against a Tahoe process. That's very much not the case: nothing in the logfiles or event stream requires the original application's source code to display. (there have been bugs in tahoe and/or foolscap which have made it seem like this must be necessary, but really, flogfiles are app-independent).

I may update the docs at some point to reflect this better.

[david-sarah <david-sarah@…>]

In 379901bf8f2b4c17:

Add 'tahoe debug flogtool' command, test for --help, and docs. This version gets the help synopses more correct, and changes the doc to say that this command is added in 1.10.0 rather than 1.9.2. fixes #1693

[david-sarah@…]

In 959248cd4917944f:

Change logging.rst to address warner's review comment. refs #1693

[davidsarah]

Post-hoc review needed for 959248cd4917944f.

[davidsarah]

Zooko was unclear on the advantage of tahoe debug flogtool over tahoe @flogtool. It is this:

tahoe @flogtool depends on there being a flogtool command on the PATH, which in turn depends on foolscap being installed. On Windows that command isn't installed correctly IIRC.

tahoe debug flogtool, OTOH, will work whenever Tahoe does, and will use the same foolscap, Twisted, and zope.interface that Tahoe uses (which is not strictly necessary but is a useful simplification).