[Distutils] Re: Distutils documentation Mac mods

[Greg Ward]

On 13 September 2000, Jack Jansen said:
> Greg,
> I've cc-d Corran on this reply, it's a bit silly to keep two conversations 
> going with similar content. Don't worry, we'll keep our esoteric Mac-talk to 
> ourselves:-)

And I'm bringing the whole SIG in on this -- surely you two aren't the
only Mac hackers in the world!

[I opined:]
> I like the model we've used for Windows installers: developers and
> packagers have to put up with a command line interface -- ie. open a
> "DOS box" and run "python setup.py bdist_wininst" -- but then end users
> have a nice little Windows-friendly executable installer.  They're not
> even aware of such a thing as the Distutils, which is how it should be
> for end-users.

[Jack replies]
> Ok, that's fine. From reading the document I got the impression that the 
> various command-line switches to install (in the end-user situation) would 
> actually be necessary relatively often, but you're saying that they're rare, 
> and that the end user will normally just do "python setup.py". Right?

Not quite.  You're right that the options to install will not be needed
very often, especially on single-user systems with no file permissions.
But the normal case is "python setup.py install" -- you CANNOT use the
Distutils without providing at least one argument to the setup script.

The rationale for this reveals my deep-seated Unix geek prejudice: how
am I supposed to find out what this program does?  Well, I run it
without arguments and see what it says.  As long as it's not a filter
(remember trying to learn how to use grep before you understood what a
filter was?), you're fine.  Well-behaved command-line programs give you
a usage summary when run with bad args or no args, and any Distutils
setup script automatically plays by those rules.

This is bad on Mac OS, where providing *any* command-line args is a
pain.  However, I have a cunning plan...

When a setup script is run under Mac OS, instead of printing a usage
summary to stdout and exiting, throw up a dialog with the user's options
-- ie. what commands they can run.  You can get a barebones list of
commands from distutils.command.__all__, and a list of all commands
(including non-standard commands provided by the current setup script)
by poking around in the Distribution object.  See 'print_commands()' in
dist.py for an example, and 'print_command_list()' for how to get the
description of each command in turn.  (The command module has to be
imported, which is why running "setup.py --help-commands" is slow and
chunky: it has to import an entire module for each line of help text!)

However, the barebones list is probably sub-optimal; you'd want to
shuffle it around a bit so "install", "build", "clean", "sdist", and
"bdist" are up at the top.  Then the sub-commands can come below,
grouped as they already are (which is a function of the ordering of
distutils.command.__all__).  This reshuffling is purely a usability
issue; 90% of users will just run "install" 90% of the time, so it
should be first, and checked by default.  Eg. here's a rough sketch of
the dialog I have in mind:

      +-------------------------------------------------------------+
      |   (x)  install      install everything from build directory |
      |   ( )  build        build everything needed to install      |
      |   ( )  clean        clean up output of 'build' command      |
      |   ( )  sdist        create a source distribution ...        |
      |   ( )  bdist        create a built (binary) distribution    |
      | ----------------------------------------------------------- |
      |   ( )  build_py     ...                                     | 
      |   ( )  build_ext    ...                                     | 
      |   ( )  build_clib   ...                                     |
      |   ( )  build_scripts ...                                    |
      |   ( )  install_lib  ...                                     |
      |   ( )  install_headers                                      |
      |   ( )  ...                                                  |
      |   ( )  bdist_dumb                                           |
      |   ( )  ...                                                  |
      |                                                             |
      |           [  Ok  ]         [ Cancel ]                       |
      +-------------------------------------------------------------+
      
(Memo to myself: if this ordering makes more sense in a GUI dialog, it
makes more sense in the output of --help-commands.  Hmmm.)

I *think* the commands should be radiobuttons, even though you can run
multiple commands in one go, because of the need to associate
command-line options with each command.

Hmmm, maybe not.  If you pick multiple commands *and* choose to "Supply
additional command-line arguments" (this would probably have to be
another checkbox, off by default), then you could get a dialog with
space for multiple argument lists: 

     Arguments for:
       build_clib       ____________________________
       install_headers  ____________________________

if the user selected to run "build_clib" and "install_headers".

You might want to use distutils.util.split_quoted() to parse those
argument strings into words, in case -- gasp! -- people use directories
with spaces in them.  (Which will have to be quoted -- ugh!  I can just
see Joe Mac User saying, "Whaddya mean, the standard shell quoting
convention?!??!")

Of course, if the user doesn't check the "Supply additional command-line
arguments" dialog, then the requested command(s) immediately run.
stdout should be preserved and presented to the user in a big scrolling
window -- yeah it's ugly, yeah it'll look like someone took a big ol'
Unix program and ported to Mac OS as quickly and cheaply as possible.
But that's what (will have) happened!

So whaddya think?  How outrageously horrible and Unix-oid is that?  I
figure it's not too bad as long as the user doesn't want to supply any
extra args, and I don't think that'll be necessary for most end-user
installation situations.

> Mac installers don't have to worry about HKEY_USER and HKEY_MACHINE and the 
> difference between OS version X and OS version Y and such: there's always a 
> single place to put things, and if that somehow changes "the old way" 
> continues to work. Usually through Apple-supplied magic, sometimes through 
> VISE-supplied magic.

What, you mean you have a *sensible* operating system?  I thought they
were banned by the secret Microsoft World Domination Act of 1994 (passed
by the hidden One World Government, of course).  (*wink*... I think.)

The issue of where to install header files affects other platforms as
well, so I think I'll bring that up in a new thread on the SIG.

        Greg
-- 
Greg Ward                                      gward@python.net
http://starship.python.net/~gward/