Python Distutils release 0.8 April 11, 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 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 /lib/python1.X/config. ( 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 , 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 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. In fact, Distutils 0.8 is exactly the code included with Python 1.6a2, so there's certainly no need to install it under Python 1.6a2. However, while Python is progressing towards 1.6 final, and the Distutils are progressing towards 1.0, there's no guarantee that releases will proceed together -- sometimes, you'll want to upgrade the Distutils in your alpha/beta Python installation to the very latest. 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 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, 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 doesn't 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 [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 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) $Id$