                            Python Distutils
                             release 0.8.2
                             April 24, 2000


INTRODUCTION
------------

The Python Distribution Utilities, or Distutils for short, are a
collection of modules that aid in the development, distribution, and
installation of Python modules.  (It is intended that ultimately the
Distutils will grow up into a system for distributing and installing
whole Python applications, but for now their scope is limited to module
distributions.)

The Distutils are a standard part of Python 1.6; if you are running 1.6,
you don't need to install the Distutils separately.  This release is
primarily so that you can add the Distutils to a Python 1.5.2
installation -- you will then be able to install modules that require
the Distutils, or use the Distutils to distribute your own modules.

More information is available at the Distutils web page:

    http://www.python.org/sigs/distutils-sig/

Any feedback, comments, bug reports, success reports, etc. should be
reported to the Distutils SIG at

    distutils-sig@python.org

If you're not yet a member of this mailing list, you can join at

    http://www.python.org/mailman/listinfo/distutils-sig

Reports of minor bugs (patches are especially welcome!) can be sent
directly to me (Greg Ward) at gward@python.net.  Anything that expects a
longer response than "Thanks for the bug report/fix!" should be directed
to the SIG.


REQUIREMENTS
------------

Release 0.8.2 of the Distutils requires Python 1.5.2 or later.
(Compatibility with Python 1.5.1 is forthcoming, as soon as I merge the
1.5.1 compatibility changes from Distutils 0.1.4 and 0.1.5 forward.)

To use the Distutils under Unix, you must have a *complete* Python
installation, including the Makefile and config.h used to build Python.
These should be in <exec-prefix>/lib/python1.X/config.  (<exec-prefix>
is the value of the --exec-prefix option to Python's configure script,
or the --prefix option if --exec-prefix wasn't supplied; if neither was
supplied, the default is "/usr/local".  If you don't know your
<exec-prefix>, fire up the Python interpreter and type
"import sys ; sys.exec_prefix".)

Certain Linux distributions break Python up into multiple packages; you
should make sure you have all required packages installed:

   Red Hat            python, python-devel
   Mandrake           python, python-devel
   SuSE               python
   Debian             python-base, python-dev

In order to build extensions on any platform, you will need a C/C++
compiler.  On Unix, the compiler used to build Python itself will be
used by default, and should do the trick; if you didn't build Python,
then hopefully you'll find out pretty quickly whether building
extensions works or not.

To build extensions on Windows, you need Microsoft Visual C++ 5.0 or
6.0.  It also helps to have access to the Windows registry from Python;
if you have the Win32 extensions (win32api, win32con) installed, you're
fine.  (Python 1.6 includes the winreg module for this purpose, which
the Distutils will use if available.)  If not, the Distutils might not
be able to find the Visual C++ executables.


INSTALLATION UNDER PYTHON 1.5.2
-------------------------------

Obviously, in order to use the Distutils you must first install them.
Since the goal of the whole project is to make distributing and
installing Python module distributions painless, this is quite easy:

    python setup.py install

Note that this installs to the "site" library directory of your local
Python installation: /usr/local/lib/python1.5/site-packages by default
on Unix, "C:\Program Files\Python" by default on Windows.  Since the
Distutils are "package-ized", the installation process will create a
subdirectory "distutils" under the site library directory.

The installation is by default quite verbose.  You can silence it with
the "-q" option:

    python setup.py -q install

but unfortunately the Distutils' verbosity is (currently) all or
nothing.


INSTALLATION UNDER PYTHON 1.6
-------------------------------

The Distutils are included with Python 1.6, so there's generally no need
to install it under Python 1.6.  However, Distutils 0.8.2 is more recent
than the code included with Python 1.6a2, so if you really like life on
the bleeding edge, you might want to install this Distutils release into 
your Python 1.6a2 library.

To do this, you'll need to hide the original Distutils package directory
from Python, so it will find the version you install.  For example,
under a typical Unix installation, the "stock" Distutils directory is
/usr/local/lib/python1.6/distutils; you could hide this from Python as
follows:

    cd /usr/local/lib/python1.6
    mv distutils distutils-orig

On Windows, the stock Distutils installation is "Lib\distutils" under
the Python directory ("C:\Python" by default for Python 1.6a2 and
later).  Again, you should just rename this directory, eg. to
"distutils-orig", so that Python won't find it.

Once you have renamed the stock Distutils directory, you can install the
Distutils as described above.


USAGE
-----

The Distutils is intended to have three user communities: developers,
packagers, and installers.  This release caters mainly to developers and
installers (system administrators, users of Python modules and
applications); there is currently a little support for generating
"built" (binary) distributions, so would-be packagers can at least start
playing with the Distutils.

Documentation for the Distutils is under construction in the form of two
manuals, "Installing Python Modules" (for installers) and "Distributing
Python Modules" (for developers and packagers).  I've included the LaTeX
source for these two manuals in the "doc" subdirectory; if you know your
way around LaTeX and the Python documentation tools, you can probably
get something out of these.  Otherwise, you're better off getting the
latest documentation from the Distutils documentation page:

    http://www.python.org/sigs/distutils-sig/doc/

These two manuals will soon be included in the standard Python
documentation set.

If you are an installer (system administrator or end-user) and you'd
like to try out the Distutils, you've already done so by installing the
Distutils themselves (thanks!).  Additionally, at least two major module
distributions (Numerical Python and PyXML) use the Distutils for
installation; if you have installed the Distutils just to get another
distributions up-and-running, follow the instructions included with that
distribution.  For any "distutil-ized" distribution, though, this should
always work:

    python setup.py install


BACKWARDS INCOMPATIBILITY NOTE
------------------------------

There are a couple of small incompatibilities between Distutils 0.1.x
and 0.8.x that affect setup scripts.  Unfortunately, two of the major
module distributions currently using the Distutils -- Numerical Python and
PyXML -- stumble across these incompatibilities.  If you need to build
and install either of these (or, in theory, any module distribution that 
used Distutils 0.1.x -- although most will not be affected), you have
two options:

  * stick with Distutils 0.1.x (to be avoided, especially if you are
    running Python 1.6)

  * replace the setup script provided by the module distribution with
    the Distutils 0.8-compatibile version provided here (recommended)

For example, if you want to build Numerical Python 15.2 using
Distutils 0.8.x, you would:

  * rename the setup.py provided with Numerical Python 15.2, eg. to
    "setup.py.orig"

  * copy "examples/numpy_setup.py" into the Numerical Python source
    tree as "setup.py"

  * run "python setup.py install" for Numerical Python as usual


EXAMPLES
--------

For developers who need to convert their own module distributions to use
the Distutils, I've included several example setup scripts in the
"examples" subdirectory.  Two of these (numpy_setup.py and xml_setup.py)
are already in production use -- in fact, xml_setup.py was stolen from
the PyXML distribution, rather than the other way around.  I am
distributing modified versions in order to provide setup scripts for
these distributions that work with Distutils 0.8 and later, and to show
some real-world examples.

If you want to try one of the example setup scripts in the real world,
you'll obviously have to have the appropriate module distribution
available: Numerical-15.2 (numpy_setup.py), PyXML-0.5.3 (xml_setup.py),
Imaging-1.0 (pil_setup.py), or mxDateTime-1.3.0 (mxdatetime_setup.py).
All you have to do is:

  * copy (or link) the provided setup script to "setup.py" in the
    target distribution (eg. copy "examples/pil_setup.py" to "setup.py"
    in Imaging-1.0, wherever you unpacked the Imaging source
    distribution)

  * run the setup script:
        python setup.py install
    to build and install the distribution to your standard Python
    library directory

Also, as always you can split the setup run up into "build" and
"install" steps:

    python setup.py build
    python setup.py install

This is handy if you just want to be sure a given module distribution
will build without actually installing it.

You can also install to a non-standard location, eg. using the --prefix
or --home options to the 'install' command:

    python setup.py install --prefix=/tmp/usr
    python setup.py install --home=/home/greg

See the "Installing Python Modules" manual for more information.
See examples/README.txt for more information on the example setup
scripts included with the Distutils.


MORE INFORMATION
----------------

I presented a paper at the Eighth International Python Conference which
covers the usage, design, and architecture of the Distutils.  The
published paper has several usage examples, which might be useful until
the real documentation is more polished.  The paper was updated
slightly and submitted to the Software Carpentry competition; you can
find both versions at the Distutils documentation page:

    http://www.python.org/sigs/distutils-sig/doc/

where you'll find links to PDF, PostScript, and HTML versions of the
paper, as well as the slides from my presentation.


BUGS AND LIMITATIONS
--------------------

The good news is that every bug/limitation that was present in this list 
in Distutils 0.1.x has been fixed, or at least addressed.  However,
there are a few outstanding problems:

  * Distutils 0.8.x doesn't yet work with Python 1.5.1
  * not well tested with Python 1.6
  * problems with specifying relative directories in an installation
    scheme
  * "bdist_dumb" command untested on Windows
  * Mac OS support only partially included
  * no test suite (hmm, is this testing thing a common theme?)
  * doesn't check to see if you're clobbering an existing module
    installation

There are some major features that still need to be added:

  * no configuration file mechanism (although it's talked about
    in the documentation)
  * no support for probing the target system for either C- or Python-
    level dependencies
  * no knowledge of whether you have installed some module distribution
    before
  * no support for running test suites
  * no support for processing documentation (and no standard
    documentation format for Python modules!)

If you think of any limitations that aren't on the above list, or find
serious bugs, or have contributions to make, come and join the Distutils 
SIG:

    http://www.python.org/mailman/listinfo/distutils-sig


FUTURE PLANS
------------

Distutils 0.9 will include support for configuration files and building
extensions on Mac OS (definitely with the MPW compiler, possibly with
CodeWarrior as well).

Distutils 1.0 will, if all goes well, be the version included with
Python 1.6 (final).  (If all does not go well, that version will be
1.0.1 or 1.0.2 or so.)


CONTRIBUTING
------------

Yes, please!  A good place to start is by reading the IPC paper and/or
presentation slides that I mentioned above.  You should probably also
read the requirements and design documents at

    http://www.python.org/sigs/distutils-sig/

if you're serious about working on the code.

Small patches can be sent to the Distutils-SIG,

    distutils-sig@python.org

for discussion by the group.  Anything larger than 200-300 lines should
be sent straight to me (gward@python.net) to reduce volume on the list.


ACKNOWLEDGMENTS
---------------

[tangible, in roughly chronological order]
  * Fred Drake: the sysconfig module
  * Amos Latteier: NT support in sysconfig
  * Perry Stoll: the MSVCCompiler class and the example setup
    script for Numerical Python, 
  * Robin Becker: registry support in msvccompiler.py 
  * Thomas Heller: more work on the registry support, several
    bug fixes in the Windows support, and just generally improving
    the code for compiling extensions on Windows
  * Eric Tiedemann: bug fixes
  * Fred Drake and Guido van Rossum: helping to figure out the
    "right way" to install third-party Python modules
  * Joe Van Andel: tweaks to the sysconfig module, misc. bug fixes
  * Corran Webster: Mac OS support in general
  * Bastian Kleineidam: the "clean" command, and a pile of
    patches, bug-fixes, and ideas, large and small
  * Lyle Johnson: bug-spotting and -fixing
  * Harry Henry Gebel: bug-spotting and -fixing; the "bztar" archive
    format

[spiritual, in roughly chronological order since the birth of the project]
  * Fred Drake and Andrew Kuchling for agreeing with me that the lack of
    a standard build mechanism is a serious hole in Python
  * the crowd at that Developer's Day session (notably Greg Stein,
    Eric Raymond, Andrew Kuchling, and a few others who I've probably
    forgotten) for a lively, stimulating, and productive (!) discussion
  * David Ascher, Guido van Rossum, and Paul Dubois for occasionally
    prodding me back to work on the Distutils
  * Paul Dubois, Andrew Kuchling, and other early adopters for finding
    bugs (and for taking a chance in general)

[spiritual, before the project ever came to be]
  * various perl5-porters: Andy Dougherty, Andreas Knig, Tim Bunce
    for showing the way with Perl's ExtUtils family of modules
  * Tim Bunce, Andreas Knig, and Jarkko Hietaniemi for showing
    the potential by developing the Perl Module List (Tim & Andreas),
    the CPAN archive (Jarkko), and the CPAN module (Andreas)

$Id: README.txt,v 1.14 2000/04/25 03:05:16 gward Exp $
