Python Module
Distribution Utilities
release 0.1
September 29, 1999
INTRODUCTION
------------
The Python Module 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 will be a standard part of Python 1.6. This release is
intended to provide a wider audience an early opportunity to try out the
system, improve its portability, shake out the bugs, make suggestions,
and so forth. Do not expect perfection: if you're trying out this
release, it should be because you want to help debug and develop, not
because you need a stable, working system immediately.
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.
INSTALLATION
------------
Obviously, in order to use the Distutils you must first install them.
Luckily, since the goal of the whole project is to make distributing and
installing Python module distributions painless, this is quite easy:
python -v 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.
Note also that the "-v" (verbose) option isn't strictly necessary.
However, one of the current limitations of the Distutils is that
verbosity is all-or-nothing, and in an early development release like
this, trust me: you want all the verbosity you can get.
USAGE
-----
The Distutils will ultimately have three user communities: developers,
distributors, and installers. This release caters to developers and
installers (system administrators and end-users); there is currently no
facility for generating "built distributions", so there's nothing for
the yet-to-exist "distributor" community to play with here.
If you are a module developer and you'd like to try out the Distutils
for your own module distribution, see the USAGE file for more
information. Also, don't forget to check out the example setup scripts
in the "examples" subdirectory.
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. However, I've included a couple of example setup
scripts to go along with some popular Python module distributions in the
"examples" subdirectory; if you happen to have one of those popular
distributions handy, you can copy the example script into its source
tree and give it a whirl. Please do this -- having as many people as
possibly trying out the system will be especially helpful in ferreting
out portability problems with the Distutils, and if you try it with wild
and wacky combinations of command-line options (as described in the
USAGE file), that will probably help find other bugs.
EXAMPLES
--------
See examples/README for more information on the example setup scripts
included with the Distutils.
BUGS AND LIMITATIONS
--------------------
Lots. Most of the code has been only lightly tested at best, and that
only on one platform (Linux). The extension-building machinery in
particular is fairly raw and heavily dependent on the OS/compiler to
behave properly. There's no (easy, documented) way to build extra C
libraries that are used by an extension module, and no way to probe the
system to see what external libraries are installed and where. Checking
for prerequisite Python modules hasn't even been considered yet.
There's no database of installed Python modules. Installation to user
home directories has been considered, but not really thought through and
certainly not tested. Providing options to one command that ought to
affect another command is a bit dodgy (and understanding why requires
understanding how the Distutils work internally). There's no support
for "built distributions", either dumb (tarball, zip file) or smart
(RPM, Wise).
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
CONTRIBUTING
------------
Yes, please! There's currently no roadmap to the code or description of
the architecture (but I'm working on the latter). You should probably
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
---------------
[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
* Barry Warsaw for encouraging me to bring it up at Developer's Day
at IPC7
* 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 and stimulating discussion
* David Ascher, Guido van Rossum, and Paul Dubois for occasionally
reminding to stop fooling around and work on the Distutils
* oh hell, everyone who's ever contributed to the Distutils SIG
[spiritual, before the project ever came to be]
* various perl5-porters: Andy Dougherty, Andreas König, Tim Bunce
for showing the way with Perl's ExtUtils family of modules
* Tim Bunce, Andreas König, and Jarkko Hietaniemi for showing
the potential by developing the Perl Module List (Tim & Andreas),
the CPAN archive (Jarkko), and the CPAN module (Andreas)
[tangible, in order by size of contribution -- yes, size matters!]
* Perry Stoll for the MSVCCompiler class and the example setup
script for Numerical Python
* Fred Drake for the sysconfig module
$Id$