mpirun --help output revamp

[nrgraham23]

This commit modifies the output from the mpirun --help
command. The options have been split into groups, to
make the output smaller and more readable. The groups
are: general, debug, output, input, mapping, ranking,
binding, devel, compatibility, launch, dvm, and
unsupported. There is also a special "full" command
that can be used to get the old behaviour of printing
out all of the options. Unsupported options may only
be seen with this full output.

This commit also adds a special case for the help
argument. It makes it possible for the user to
enter 0 or 1 arguments instead of having to always
enter an argument. This defaults to printing out
the "general" help options so the user can then
see what help arguments there are.

Fixes #2931

Signed-off-by: Nathaniel Graham [email protected]

[nrgraham23]

This message still needs to be cleaned up, but I wanted to get the everything up so people could look at it and comment on it.

[nrgraham23]

@jsquyres @rhc54 @hppritcha Please review

[hppritcha]

@nrgraham23 could you rebase to fix the conflicts?

[nrgraham23]

@hppritcha #3242 created the conflict. I have rebased and fixed the help message, so this is good to go unless there is a request for a change.

[hjelmn]

@nrgraham23 For bonus points if you can add a --help-parsable (or something similar) that would be awesome. Right now the completion scripts hand-code the options so need to be updated every time an option is added/removed. You can take a look at ompi_info's parsable output for an example.

If you do that I will totally write bash/zsh completion scripts for all of our user-facing binaries.

[nrgraham23]

@hjelmn I will check that out. Probably won't get to it until next week though.

[nrgraham23]

Going to merge this afternoon if there are no objections.

[nrgraham23]

This has been up for a week, merging now.

[jsquyres]

I notice that after this PR, I get output like this:

$ mpirun --help
mpirun (Open MPI) 4.0.0a1

Usage: mpirun [OPTION]...  [PROGRAM]...
Start the given program using Open RTE

   -am <arg0>            Aggregate MCA parameter set file list
   --app <arg0>          Provide an appfile; ignore all other command line
                         options
-c|-np|--np <arg0>       Number of processes to run
   -fwd-mpirun-port|--fwd-mpirun-port 
                         Forward mpirun port to compute node daemons so all
                         will use it
-h|--help <arg0>         Help  messages.  Argument options are: general
                         (Defaults to this option), debug, output, input,
                         mapping, ranking, binding, devel (arguments usefull
                         to OMPI Developers), compatibility (arguments
                         supported for backwards compatibility) launch
                         (arguments to modify launch options), and dvm
                         (Distributed Virtual Machine arguments
   -N <arg0>             Launch n processes per node on all allocated nodes
                         (synonym for npernode)
   -n|--n <arg0>         Number of processes to run
-q|--quiet               Suppress helpful messages
   -report-pid|--report-pid <arg0>  
                         Printout pid on stdout [-], stderr [+], or a file
                         [anything else]
   -report-uri|--report-uri <arg0>  
                         Printout URI on stdout [-], stderr [+], or a file
                         [anything else]
   -tune <arg0>          Application profile options file list
-v|--verbose             Be verbose
-V|--version             Print version and exit
-x <arg0>                Export an environment variable, optionally
                         specifying a value (e.g., "-x foo" exports the
                         environment variable foo and takes its value from
                         the current environment; "-x foo=bar" exports the
                         environment variable name foo and sets its value to
                         "bar" in the started processes)

Report bugs to http://www.open-mpi.org/community/help/

I'm sorry I missed the review period, but I have two questions / observations:

1. How were the default list of CLI params picked for mpirun --help? Some of them are fairly esoteric, and probably don't need to be in the default listing.
2. There doesn't seem to be any information on this default help output telling you how to get more information. Can we add something? For example, here's what git does:

$ $ git --help | tail -n 3
'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.

[nrgraham23]

1: The default list of options was picked from the "General" category of options from the categories listed in the google doc linked in #2931

2: Currently the optional arguments are listed in the help message:

-h|--help Help messages. Argument options are: general
(Defaults to this option), debug, output, input,
mapping, ranking, binding, devel (arguments usefull
to OMPI Developers), compatibility (arguments
supported for backwards compatibility) launch
(arguments to modify launch options), and dvm
(Distributed Virtual Machine arguments

I was a little surprised no one had any comments on the changes, but I would be happy to make changes.

[jsquyres]

@nrgraham23 Ah, gotcha on both points. Sorry I missed these points during review. 😦

Let's do two things:

1. Reclassify some of the params away from general:
   • -am: launch options
   • -app: launch options
   • -fwd-mpirun-port: launch options
   • -N: mapping options (right?) -- also, it's listed as a synonym for a backwards compat option. That should be fixed (is it is synonym for something else?)
   • -report-pid: debugging options
   • -report-uri: debugging options
   • -tune: debugging options
   • -x: launching options
2. Move the bulk of the -h message (i.e., how to get more help) to a separate output at the bottom, sorta like git.

[nrgraham23]

@jsquyres Thats alright. The first changes will be fairly simple. The second change may take a little hacking. I should have time to make the changes and get a PR up tomorrow.

[jsquyres]

Thank you!

@rhc54 @hppritcha What do you guys think of my re-classifications (above)?

[hppritcha]

Looks good to me.