Command line help for include-what-you-use requires knowing the -Xiwyu flag

[GoogleCodeExporter]

When passing --help to the include-what-you-use binary, we get what looks like 
a clang usage message, followed by:

error: unable to handle compilation, expected exactly one compiler job in ''
/home/rpavlik/src/third-party/llvm/tools/clang/tools/include-what-you-use/iwyu.c
c:3704: Assertion failed: compiler && "Failed to process argv"
Aborted

When passing -h, the clang usage message isn't printed, but this error message 
is:

error: no input files
error: unable to handle compilation, expected exactly one compiler job in ''
/home/rpavlik/src/third-party/llvm/tools/clang/tools/include-what-you-use/iwyu.c
c:3704: Assertion failed: compiler && "Failed to process argv"
Aborted

The only way I could get the help to display was to call something like 
"include-what-you-use -Xiwyu -h"  which gave two errors around the usage info:

include-what-you-use: invalid option -- 'h'
USAGE: iwyu [-Xiwyu --iwyu_opt]... <clang opts> <source file>
Here are the <opts> you can specify:
   --check_also=<glob>: tells iwyu to print iwyu-violation info
        for all files matching the given glob pattern (in addition
        to the default of reporting for the input .cc file and its
        associated .h files).  This flag may be specified multiple
        times to specify multiple glob patterns.
   --cwd=<dir>: tells iwyu what the current working directory is.
   --help: prints this help and exits.
   --howtodebug[=<filename>]: with no arg, prints instructions on
        how to run iwyu under gdb for the input file, and exits.
        With an arg, prints only when input file matches the arg.
   --mapping_file=<filename>: gives iwyu a mapping file.
   --transitive_includes_only: do not suggest that a file add
        foo.h unless foo.h is already visible in the file's
        transitive includes.
   --verbose=<level>: the higher the level, the more output.

FATAL ERROR: unknown flag.

Alternately -Xiwyu --help displayed the usage text without the two errors.

Original issue reported on code.google.com by ryan.pav...@gmail.com on 20 Nov 2012 at 8:08

[GoogleCodeExporter]

Yes, I think there are (at least :-) two issues here:

1) Handle --help and -h in a reasonable way
2) What happens when no input file is provided -- it drives me crazy that IWYU 
aborts here.

I don't know if it's critical that we can display Clang's help text.

Original comment by kim.gras...@gmail.com on 21 Nov 2012 at 6:12

[GoogleCodeExporter]

I think we can use --help to display IWYU help and recommend to use "clang 
--help" for Clang help. But I don't know what does "clang -h" mean. Clang 
reports
> clang: error: no input files
So need to investigate the purpose of -h flag before using it to display IWYU 
help. 

Original comment by vsap...@gmail.com on 25 Nov 2012 at 10:49

[GoogleCodeExporter]

IWYU prints help for any unknown flag. It looks like the correct invocation to 
get IWYU help is;

 $ include-what-you-use --Xiwyu --help

That shows help without complaining.

I guess we can't be sure that clang is available -- if we ever come around to 
using IWYU, it will be for code only compiled with GCC and MSVC, so it'd be 
nice if IWYU was stand-alone.

I wonder if it would be possible to trap '--help' and redirect clang's help to 
'--clang-help' or something.

Original comment by kim.gras...@gmail.com on 26 Nov 2012 at 6:05

[GoogleCodeExporter]

Attached is a simple patch to have IWYU get "--help" unescaped. That means 
there's no way to get at Clang's help, but I'm not sure that's a problem. It 
would be easy to add another magic word to dispatch to Clang's help, if someone 
can think of a good switch.

Original comment by kim.gras...@gmail.com on 10 Dec 2012 at 7:52

Attachments:

• help-switch.patch

[GoogleCodeExporter]

Oh, and it changes the USAGE text to refer to the executable as 
"include-what-you-use" instead of "iwyu". I sure hope the executable name being 
"include-what-you-use" is not just a thing on Windows...

Original comment by kim.gras...@gmail.com on 10 Dec 2012 at 8:02

[GoogleCodeExporter]

And another patch to get rid of the chaotic behavior where IWYU calls abort() 
if invoked without arguments.

Original comment by kim.gras...@gmail.com on 10 Dec 2012 at 8:07

Attachments:

• no-abort-for-no-input.patch

[GoogleCodeExporter]

These patches have been applied as of r396, and I'm happy with the current 
behavior. ryan.pavlik, could you update your local copy and see if you think 
this issue can be closed?

Original comment by kim.gras...@gmail.com on 27 Dec 2012 at 2:48

[GoogleCodeExporter]

Looks pretty good to me!  The only nit I could pick is that the usage line says 
"include-what-you-use [-Xiwyu --iwyu_opt] ...."

then says "Here are the <opts> you can specify" - perhaps somehow make this 
more clearly indicate that it means the options substituted in for --iwyu_opt?

Original comment by ryan.pav...@gmail.com on 4 Jan 2013 at 8:00

[GoogleCodeExporter]

I saw that the other day and did a double-take too. I think it would be worth 
addressing. Volodymyr, could you clarify it, or would you like me to send a 
patch?

Original comment by kim.gras...@gmail.com on 4 Jan 2013 at 10:00

[GoogleCodeExporter]

Would
  Here are the <iwyu_opts> you can specify:
be clear enough?

Or is it better with an example?
  Here are the <iwyu_opts> you can specify (e.g. -Xiwyu --verbose=3):

Original comment by vsap...@gmail.com on 7 Jan 2013 at 7:45

[GoogleCodeExporter]

I think either is fine.

Original comment by kim.gras...@gmail.com on 7 Jan 2013 at 7:53

[GoogleCodeExporter]

Looks good to me, I think this one can be closed.

Original comment by ryan.pav...@gmail.com on 14 Jan 2013 at 12:38

[GoogleCodeExporter]

Fixed in r394, r395, r396 and r427.

Original comment by kim.gras...@gmail.com on 20 Jan 2013 at 9:05

• Changed state: Fixed