[Distutils] setup.py command-line syntax

[Greg Ward]

OK, time for the first of those unresolved issues.  This one isn't
actually mentioned as such in the "Unresolved issues" section of the
design proposal, because if you carefully read and think through what's
already there you'll start to see the holes in my proposal.  In
particular, we need to figure out what the syntax for the 'setup.py'
command line is going to be.  I have a couple of ideas, none of them
wholly satisfactory.

In vague terms, I'm currently thinking that the syntax will be like
this:

   ./setup.py [global_options] cmd1 [cmd1_options] [cmd2 [cmd2_options]] ...

The specific problem I'm having is: what will options look like, in
particular options with arguments, and how do we know when the options
for cmd1 are over and we're staring at cmd2?

Option 1: getopt-ish

Options are either of the '-x' form (single dash, single letter, may be
jammed together, arguments may follow with or without intervening space)
or of '--long-opt' form (two dashes, dash-or-underscore-separated-words,
arguments will follow either '=' or whitespace).

Pros:
 * familar interface: just like the getopt module, except that there
   are these "command" things intermingled with options, and there are
   multiple sources for option descriptors (the standard 'Distribution'
   class provided by distutils.setup.core, the individual command
   classes provided by the command modules, and possibly setup.py).

Cons: 
 * those complications mean that we'd have to reimplement the getopt
   module for distutils, with hooks to the various sources of option
   descriptors specific to distutils
 * due to many ways of specifying option arguments ("-a foo", "-afoo",
   "--aardvark=foo", "--aardvark foo"), can't tell where option lists
   ends and next command begins without fully processing the option
   descriptors and argument lists.  This could induce temporal whiplash.


Option 2: restricted getopt-ish

Options are only of the '--long-opt' form, and option arguments may only 
be specified as '--option=value' -- no spaces between option and value
(ie. they're the same command line word).

Pros:
  * much easier to implement than a getopt knock-off
  * don't have to fully process options to know where cmd1's options
    stop and cmd2 starts: just look for first ! /^--/ after cmd1
  * easy to make a standard way to negate boolean (no argument) 
    options: just accept "--no-flag" in addition to "--flag"

Cons:
  * perversion of a familiar interface; people will think that because
    they can say "--option=value" they can equivalently say "--option
    value" and will get confused when distutils tells them "no such
    command 'value'" (err, except it will *also* tell them 
    "option '--option' requires an argument"... maybe not so bad then)
  * needless typing; double-dashes on long options are really only 
    necessary to distinguish them from short options, and if we
    don't support short options why bother with the double dashes?


Option 3: who needs dashes anyways?

Options are always of the "option=value" form -- no dashes, must always
have a value (even if that value is only 'yes' or 'no').

Pros:
  * simple to implement, simple to explain
  * no confusion with existing interfaces (except... see "Cons")
  * dead easy to spot end of 'option=value' list after each command

Cons:
  * looks like we're running a Makefile!
  * no nice way to do boolean (argument-less) options


Option 4: who needs command options anyways?

Change the syntax to

  ./setup.py [options] cmd1 [cmd2 ...]

and make all options the responsibility of distutils.core (or ensure
that the client seutp.py and the various command classes get their
option descriptors to distutils.core).

Pros:
  * assuming we can get all the option descriptors to distutils.core in
    time, can just use standard 'getopt' module; the leftover arguments
    are of course the commands

Cons:
  * unclear from the command-line whose responsibility each option is


Anyone have any other schemes?  Comments on these?  Preferences?

        Greg
-- 
Greg Ward - software developer                    gward@cnri.reston.va.us
Corporation for National Research Initiatives    
1895 Preston White Drive                      voice: +1-703-620-8990 x287
Reston, Virginia, USA  20191-5434               fax: +1-703-620-0913