[Distutils] Draft of new setuptools installation instructions

[Phillip J. Eby]

I'm working on new installation instructions for setuptools 0.6c4, which 
will no longer use ez_setup.py for end-user manual installation of 
setuptools (as opposed to bundled installation with another package).

The basic idea is that the PyPI page for setuptools would contain these 
instructions, and links to the various setuptools documentation 
pages.  ez_setup will still be available for as an importable module for 
people to integrate with their setuptools-using packages, but when run as a 
script, ez_setup.py will simply tell people to consult the PyPI page.

I'm looking for any feedback people might have, on the installation process 
itself or on the directions.  Some particular areas of question/concern:

* Should ez_setup perhaps launch a web browser pointing to these 
instructions, instead of trying to download setuptools itself?  (This would 
bypass most of those annoying proxy problems right off the bat, at least 
when just installing setuptools.)

* Should we make more effort to create a usable command-line experience on 
Windows?  Perhaps use a post-install script to register easy_install so it 
works from "Start/Run", with an automatic pause to prevent the opened 
console window from closing when it finishes running?  Should we include 
optional registration for the ``.egg`` extension so downloading or 
double-clicking an egg installs it?

* The new install procedure bypasses firewall issues for installing 
setuptools itself, but doesn't do anything about the issue for packages 
that have dependencies.  Is there anything else that can be done about that?

Anyway, those are the questions; here are the docs so far:


-------------------------
Installation Instructions
-------------------------


Windows
=======

Install setuptools using the provided ``.exe`` installer.  If you've 
previously installed older versions of setuptools, please delete all 
``setuptools*.egg`` files from your system FIRST.

If you are upgrading a previous version of setuptools that was installed 
using an ``.exe`` installer, please be sure to also uninstall that older 
version via your system's "Add/Remove Programs" feature, BEFORE installing 
the newer version.


RPM-Based Systems
=================

Install setuptools using the provided source RPM.  The included ``.spec`` 
file assumes you are installing using the default ``python`` executable, 
and is thus not specific to a particular Python version.  The 
``easy_install`` executable will be installed to a system ``bin`` directory 
such as ``/usr/bin``.

If you wish to install to a custom installation location, please use the
``.egg`` installation approach described in the following section.


Cygwin, Mac OS X, Linux, Other
==============================

1. Download the appropriate egg for your version of Python (e.g.
    ``setuptools-0.6c4-py2.4.egg``).  Do NOT rename it.

2. Make it executable (e.g. ``chmod +x setuptools-0.6c4-py2.4.egg``)

3. Run it (e.g. ``./setuptools-0.6c4-py2.4.egg``).  Setuptools will
    install itself using the matching version of Python (e.g.
    ``python2.4``), and will place the ``easy_install`` executable
    in the default location for installing Python scripts.

If you want to install setuptools to somewhere other than ``site-packages`` 
or your default distutils installation locations for libraries and scripts, you
may use EasyInstall command-line options such as ``--prefix``, 
``--install-dir``, and so on.  You can use ``--help`` to get a full options 
list, but we recommend consulting the `EasyInstall manual`_ for detailed 
instructions, especially `the section on custom installation locations`_.


Cygwin Note
-----------

If you are trying to install setuptools for the *Windows* version of Python (as
opposed to the Cygwin version that lives in ``/usr/bin``), you must make sure
that an appropriate executable (``python2.3``, ``python2.4``, or ``python2.5``)
is on your ``PATH`` when invoking the egg.  For example, doing the following at
a Cygwin bash prompt will install setuptools for the *Windows* Python found at
``C:\\Python24``::

     ln -s /cygdrive/c/Python24/python.exe python2.4
     PATH=.:$PATH ./setuptools-0.6c4-py2.4.egg
     rm python2.4