Open MPI logo

Open MPI Development Mailing List Archives

  |   Home   |   Support   |   FAQ   |   all Development mailing list

Subject: Re: [OMPI devel] RFC: mpirun options
From: Jeff Squyres (jsquyres_at_[hidden])
Date: 2010-04-20 17:34:54


Just so there's *some* reply... I'm obviously in favor of this RFC. ;-)

On Apr 19, 2010, at 2:53 PM, Eugene Loh wrote:

> Jeff and I were talking about trac 2035 and the handling of mpirun
> command-line options. While most mpirun options have long,
> multi-character names prefixed with a double dash, OMPI had originally
> also wanted to support combinations of short names (e.g., "mpirun -hvq",
> even if we don't document such combinations) as well as legacy
> single-dash names (e.g., "-host"). To improve diagnosibility of error
> messages and simplify the source code and user documentations, some
> simplifications seemed in order. Since the command-line parsing is
> shared not only by mpirun but by all OMPI command-line interfaces,
> however, Jeff suggested an RFC. So, here goes.
>
> RFC: Drop mpirun Short-Name Combinations
>
> WHAT: No longer support the combination of multiple mpirun short-name (single-character) options into a single argument. E.g., do not allow users to combine mpirun -h -q -v into mpirun -hqv.
>
> Also, no longer describe separate single-dash and double-dash names such as -server-wait-time and --server-wait-time. Simply give one name per option and indicate that it could be prefixed with either a single or a double dash.
>
> WHY: To improve the diagnosibility of error messages and simplify the description and support of mpirun options.
>
> WHERE: Basically, in opal/util/cmd_line.c.
>
> WHEN: Upon acceptance.
>
> TIMEOUT: May 7, 2010.
>
> WHY (details)
>
> Definitions
>
> There are three kinds of mpirun option names:
>
> kind of name prefix length example
> long name -- multi-character --verbose
> short name - single-character -v
> single-dash name - multi-character -np
> Background
>
> We had wanted to support long and short names.
>
> Short names were supposed to be combinable. E.g., instead of ls -l -t -r, just write ls -ltr.
>
> To support backwards compatibility with options that had become well-known from other MPI implementations, we also wanted to support certain short names, such as -np or -host. That is, even though the option starts with a single-dash, we would first check to see if it were a special recognized "single-dash" option name. Only if that check failed would we expand the argument further to parse it as a combination of short names.
>
> Obfuscates Error Messages
>
> Unfortunately, the resulting, more complicated grammar leads to misleading error messages. E.g., consider this example from trac 2035:
>
> % mpirun -tag-output -np 4 -nperslot 1 -H saem9,saem10 hostname
> --------------------------------------------------------------------------
> mpirun was unable to launch the specified application as it could not find an executable:
>
> Executable: -p
> Node: saem9
>
> while attempting to start process rank 0.
> --------------------------------------------------------------------------
>
> The point of the ticket was mostly that a misspelled option is handled as an unfound executable, but it also points out that we end up reporting on an option (-p) that from the user's perspective isn't even on the command line in the first place. What has happened is that an option (-nperslot) was not recognized, the first character (n) was recognized, the option was parsed as a combination of short names, and one of those short names (-p) was not recognized.
>
> There are different ways of cleaning all of this up, but a simple solution is just not to support short-name combinations.
>
> Fringe Functionality
>
> The ability to combine short names into a single "-" option is fringe functionality for mpirun anyhow.
>
> We don't document this ability in the first place.
>
> Further, we don't have that many short names -- 10, out of a total of 82 options -- and many combinations don't make much sense. The ability to combine options makes most sense for utilities that use short option names, and then if those options don't take arguments. E.g., ls -ltr in place of ls -l -t -r. The mpirun options just aren't like that.
>
> Simplify Single-/Double-Dash Usage
>
> We were going to support single-dash (multi-character) names only sparingly and only for backwards compatibility with well-established options from other MPIs. In reality, we routinely add a single-dash name for each new option we introduce.
>
> We end up having both single-dash and double-dash names, making both source code and user documentation less readable.
>
> However, ultimately the source code doesn't even check these distinctions when parsing the mpirun command line. For example, we go to the effort in our source code and user documentation to distinguish between -server-wait-time and --server-wait-time, and between -rf and --rankfile. When options are parsed, however, we disregard any such distinctions. E.g., --rf and -rankfile are recognized.
>
> Other Issues
>
> The command-line parser is not only for mpirun, however, but for all OMPI command-line interfaces. Hence, this RFC. _______________________________________________
> devel mailing list
> devel_at_[hidden]
> http://www.open-mpi.org/mailman/listinfo.cgi/devel
>

-- 
Jeff Squyres
jsquyres_at_[hidden]
For corporate legal information go to:
http://www.cisco.com/web/about/doing_business/legal/cri/