Hi all --
well, you can pretty much ignore the fragment of "Installing Python Modules" that I announced yesterday. I had a brief chat with Guido this afternoon, and he pretty much torpedoed the lovely, baroque scheme that Fred Drake and I cooked up and which became said document. Sigh.
Anyways, here's a rough outline of the New New Installation Scheme (whatever you may say, you can't accuse me of inflexible thinking...):
* as before, a standard installation (to $prefix/lib/python1.X/site-packages on Unix, or C:\Program Files\Python on Windows) is painless(TM): python setup.py install
* for a custom installation where you don't care about supporting multiple platforms, install-lib is the option normally used: python setup.py install --install-lib=/home/greg/lib/python python setup.py install --install-lib=/tmp/pylib python setup.py install --install-lib=d:\Temp\Python\Lib
In most circumstances, top-level modules are installed right in the 'install-lib' directory.
* if you do care about a multi-platform installation, you should supply both 'install-lib' and 'install-platlib': the former will be used for pure Python module distributions, the latter for module distributions containing extensions:
python setup.py install --install-lib=~/lib/python \ --install-platlib=~/lib/python.linux-x86
A subtle wrinkle: for any given module distribution, only one of these is necessary. I don't think installers should have to be aware of the implementation details of the software they're installing, though, so the safe thing to do is supply both options -- and the likely way to do this will be through a config file. Not sure how the config file will look, though.
* the only reason to supply 'prefix' and 'exec-prefix' is to install a module distribution to a different Python installation than the one expected by the current interpreter. Say you have a Python installation in /usr and another one in /usr/local: /usr/bin/python setup.py --prefix=/usr/local This will install modules to /usr/local/lib/python1.X/site-packages. (This could be one solution to the "problem" of Linux distributions shipping Python in /usr, but wanting to keep third-party modules in /usr/local -- just create a dummy /usr/local/lib/python1.X/site-packages and you're off to the races.)
* 'install-path' is still there, and its purpose is still to supply an extra sub-path to append to 'install-lib', so that non-package-ized module distributions will still get a directory of their own. If 'install-path' used and 'install-lib' is not -- i.e. we're installing to a site-packages directory under some prefix or exec-prefix (or directly in prefix/exec-prefix on Windows) -- then Distutils will also create a .pth file pointing to the 'install-path' directory.
There are a few tricky issues with 'install-path', though: + should installers be allowed to set it, or should it be a developer-only option? + if the installer supplied 'install-lib' and/or 'install-platlib', do we still respect 'install-path', i.e. do we still append 'install-path' to 'install-lib'? We certainly don't create a .pth file in that case (Python will ignore it). + do we allow installers to supply *both* 'install-lib' and 'install-path'? I vote YES on all three, but I'd like to hear who agrees with me and who is a hopelessly misguided heretic. >grin<
* default values: prefix: sys.prefix exec-prefix: if installer supplied prefix: prefix else: sys.exec_prefix
install-lib: $prefix/lib/python1.X/site-packages install-platlib: if installer supplied install-lib: install-lib else: $exec-prefix/lib/python1.X/site-packages
* installation rules if install-path not supplied: modules from pure Python distribution go to install-lib modules from distribution with extensions go to install-platlib
* installation rules if install-path supplied: modules from pure Python distribution go to install-lib + install-path modules from distribution with extensions go to install-platlib + install-path
Note that the "install-path not supplied" case is just a special case of "install-path supplied", where install-path is an empty string. But it's worth documenting it separately, because it's the usual case.
I think I like this scheme better than the other two I've tried. Please let me know what you think: I'll rewrite the "Custom Installation" section and then rewrite the code to match the docs Real Soon Now.