Python Module Distribution Utilities release 0.1.1 October 23, 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$