Note that any pathnames (files or directories) supplied in the setup

script should be written using the Unix convention, i.e.

slash-separated. The Distutils will take care of converting this

platform-neutral representation to whatever is appropriate on your

current platform before actually using the pathname. This makes your

setup script portable across operating systems, which of course is one

of the major goals of the Distutils. In this spirit, all pathnames in

this document are slash-separated (Mac OS users should keep in mind that

the \emph{absence} of a leading slash indicates a relative directory,

the opposite of the Mac OS convention with colons).

\begin{tableiii}{l|l|c}{code}%

{Format}{Description}{Notes}

\lineiii{zip}{zip file (\file{.zip})}{(1)}

\lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}

\lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}

\lineiii{tar}{tar file (\file{.tar})}{}

\end{tableiii}

\noindent Notes:

\begin{description}

\item[(1)] default on Windows

\item[(2)] default on Unix

\end{description}

Following the Distutils' own manifest template, let's trace how the

\command{sdist} command will build the list of files to include in the

Distutils source distribution:

Just like in the setup script, file and directory names in the manifest

template should always be slash-separated; the Distutils will take care

of converting them to the standard representation on your platform.

That way, the manifest template is portable across operating systems.

\item if the manifest file, \file{MANIFEST} doesn't exist, read

\file{MANIFEST.in} and create the manifest

\item if \file{MANIFEST.in} is more recent than \file{MANIFEST},

recreate \file{MANIFEST} by reading \file{MANIFEST.in}

A ``built distribution'' is what you're probably used to thinking of

either as a ``binary package'' or an ``installer'' (depending on your

background). It's not necessarily binary, though, because it might

contain only Python source code and/or byte-code; and we don't call it a

package, because that word is already spoken for in Python. (And

``installer'' is a term specific to the Windows world. \XXX{do Mac

people use it?})

A built distribution is how you make life as easy as possible for

installers of your module distribution: for users of RPM-based Linux

systems, it's a binary RPM; for Windows users, it's an executable

installer; for Debian-based Linux users, it's a Debian package; and so

forth. Obviously, no one person will be able to create built

distributions for every platform under the sun, so the Distutils is

designed to enable module developers to concentrate on their

specialty---writing code and creating source distributions---while an

intermediary species of \emph{packager} springs up to turn source

distributions into build distributions for as many platforms as there

are packagers.

Of course, the module developer could be his own packager; or the

packager could be a volunteer ``out there'' somewhere who has access to

a platform which the original developer does not; or it could be

software periodically grabbing new source distributions and turning them

into built distributions for as many platforms as the software has

access to. Regardless of the nature of the beast, a packager uses the

setup script and the \command{bdist} command family to generate built

distributions.

As a simple example, if I run the following command in the Distutils

source tree:

\begin{verbatim}

\end{verbatim}

then the Distutils builds my module distribution (the Distutils itself

in this case), does a ``fake'' installation (also in the \file{build}

directory), and creates the default type of built distribution for my

platform. In Distutils 0.8, only two types of built distribution are

supported: \code{gztar} (default on non-Linux Unix) and \code{zip}

(default on Windows). Thus, the above command on a Unix system creates

\file{Distutils-0.8.built-posix.tar.gz}; unpacking this tarball from

Python's \filevar{prefix} directory installs the Distutils just as

though you had downloaded the source distribution and run \code{python

setup.py install}. Obviously, for pure Python distributions, this

isn't a huge win---but for non-pure distributions, which include

extensions that would need to be compiled, it can mean the difference

between someone being able to use your extensions or not.

\XXX{filenames are inaccurate here!}

The \command{bdist} command has a \option{--format} option, similar to

the \command{sdist} command, that you can use to select which formats to

generate: for example,

\begin{verbatim}

\end{verbatim}

would, when run on a Unix system, create

\file{Distutils-0.8.built-posix.tar.gz}---again, this archive would be

unpacked from Python's \filevar{prefix} directory to install the

Distutils.

The available formats for built distributions are:

\begin{tableiii}{l|l|c}{code}%

{Format}{Description}{Notes}

\lineiii{zip}{zip file (\file{.zip})}{(1)}

\lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(2)}

\lineiii{ztar}{compressed tar file (\file{.tar.Z})}{}

\lineiii{tar}{tar file (\file{.tar})}{}

\lineiii{rpm}{RPM}{(3)}

\lineiii{srpm}{source RPM}{}

\lineiii{wise}{Wise installer for Windows}{}

\end{tableiii}

\noindent Notes:

\begin{description}

\item[(1)] default on Windows

\item[(2)] default on Unix

\item[(3)] not implemented yet; will be default on RPM-based Linux

systems

\item[(5)] not implemented yet; will be default on Windows

\end{description}

You don't have to use the \command{bdist} command with the

\option{--formats} option; you can also use the command that directly

implements the format you're interested in. Many of these

\command{bdist} ``sub-commands'' actually generate several similar

formats; for instance, the \command{bdist\_dumb} command generates all

the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and

\code{zip}), and \command{bdist\_rpm} generates both binary and source

RPMs. The \command{bdist} sub-commands, and the formats generated by

each, are:

\begin{tableii}{l|l}{command}%

{Command}{Formats}

\lineii{bdist\_dumb}{tar, ztar, gztar, zip}

\lineii{bdist\_rpm}{rpm, srpm}

\lineii{bdist\_wise}{wise}

\end{tableii}