Using the Distutils is quite simple, both for module developers and for users/administrators installing third-party modules. As a developer, your responsibilities (apart from writing solid, well-documented and well-tested code, of course!) are:
Not all module developers have access to a multitude of platforms, so it's not always feasible to expect them to create a multitude of built distributions. It is hoped that a class of intermediaries, called packagers, will arise to address this need. Packagers will take source distributions released by module developers, build them on one or more platforms, and release the resulting built distributions. Thus, users on the most popular platforms will be able to install most popular Python module distributions in the most natural way for their platform, without having to run a single setup script or compile a line of code.
The setup script is usually quite simple, although since it's written in Python, there are no arbitrary limits to what you can do with it.1 If all you want to do is distribute a module called foo, contained in a file foo.py, then your setup script can be as little as this:
from distutils.core import setup setup(name="foo", version="1.0", py_modules=["foo"])
To create a source distribution for this module, you would create a setup script, setup.py, containing the above code, and run:
python setup.py sdist
which will create an archive file (e.g., tarball on Unix, ZIP file on Windows) containing your setup script, setup.py, and your module, foo.py. The archive file will be named Foo-1.0.tar.gz (or .zip), and will unpack into a directory Foo-1.0.
If an end-user wishes to install your foo module, all she has to do is download Foo-1.0.tar.gz (or .zip), unpack it, and--from the Foo-1.0 directory--run
python setup.py install
which will ultimately copy foo.py to the appropriate directory for third-party modules in their Python installation.
This simple example demonstrates some fundamental concepts of the
Distutils: first, both developers and installers have the same basic
user interface, i.e. the setup script. The difference is which
Distutils commands they use: the
sdist command is
almost exclusively for module developers, while
more often for installers (although most developers will want to install
their own code occasionally).
If you want to make things really easy for your users, you can create
one or more built distributions for them. For instance, if you are
running on a Windows machine, and want to make things easy for other
Windows users, you can create an executable installer (the most
appropriate type of built distribution for this platform) with the
bdist_wininst command. For example:
python setup.py bdist_wininst
will create an executable installer, Foo-1.0.win32.exe, in the current directory.
Currently (Distutils 0.9.2), the only other useful built
distribution format is RPM, implemented by the
command. For example, the following command will create an RPM file
python setup.py bdist_rpm
(This uses the
rpm command, so has to be run on an RPM-based
system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by running
python setup.py bdist --help-formats
If you're reading this document, you probably have a good idea of what modules, extensions, and so forth are. Nevertheless, just to be sure that everyone is operating from a common starting point, we offer the following glossary of common Python terms:
sys.pathcan contribute modules to the root package.
The following terms apply more specifically to the domain of distributing Python modules using the Distutils: