\documentclass{howto}

\usepackage{ltxmarkup}

\usepackage{times}

\usepackage{distutils}

\title{Distributing Python Modules}

\author{Greg Ward}

\authoraddress{E-mail: \email{[email protected]}}

\begin{document}

\maketitle

\tableofcontents

\section{Introduction}

\label{intro}

In the past, Python module developers have not had much infrastructure

support for distributing modules, nor have Python users had much support

for installing and maintaining third-party modules. With the

introduction of the Python Distribution Utilities (Distutils for short)

in Python 1.6, this situation should start to improve.

This document only covers using the Distutils to distribute your Python

modules. Using the Distutils does not tie you to Python 1.6, though:

the Distutils work just fine with Python 1.5, and it is reasonable (and

expected to become commonplace) to expect users of Python 1.5 to

download and install the Distutils separately before they can install

your modules. Python 1.6 users, of course, won't have to add anything

to their Python installation in order to use the Distutils to install

third-party modules.

This document concentrates on the role of developer/distributor: if

you're looking for information on installing Python modules, you should

refer to the ``Installing Python Modules'' manual.

\section{Concepts \& Terminology}

\label{concepts}

Using the Distutils is quite simple, both for module developers and for

users/administrators installing third-party modules. As a developer,

your responsibilites (apart from writing solid, well-documented and

well-tested code, of course!) are:

\begin{itemize}

\item write a setup script (\file{setup.py} by convention)

\item (optional) write a setup configuration file

\item create a source distribution

\item (optional) create one or more built (binary) distributions

\end{itemize}

Each of these tasks is covered in this document.

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

\emph{packagers}, will arise to take 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.

\subsection{A simple example}

\label{simple-example}

The setup script is usually quite simple, although since it's written in

Python, there are no arbitrary limits to what you can do. If all you

want to do is distribute a module called \module{foo}, contained in a

file \file{foo.py}, then you can get away with as little as this:

\begin{verbatim}

from distutils.core import setup

setup (name = "foo",

version = "1.0",

py_modules = ["foo"])

\end{verbatim}

Some observations:

\begin{itemize}

\item all information that you supply to the Distutils is supplied as

keyword arguments to the \function{setup()} function

\item those keyword arguments fall into two categories: package

meta-data (name, version number) and information about what's in the

package (list of pure modules, in this case)

\item modules are specified by module name, not filename (the same will

hold true for packages and extensions)

\item it's recommended that you supply a little more meta-data, in

particular your name, email address and a URL for the project

\end{itemize}

To create a source distribution for this module, you would run

\begin{verbatim}

python setup.py sdist

\end{verbatim}

which will create an archive file (e.g., tarball on Unix, zip file on

Windows) containing your setup script, \file{setup.py}, and your module,

\file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or

\file{.zip}), and will unpack into a directory \file{Foo-1.0}.

If an end-user wishes to install your \module{foo} module, all she has

to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it,

and---from the \file{Foo-1.0} directory---run

\begin{verbatim}

python setup.py install

\end{verbatim}

which will ultimately copy \file{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 \emph{commands} they use: the \command{sdist} command is

almost exclusively for module developers, while \command{install} is

more often for installers (although most developers will want to install

their own code occasionally).

\XXX{only partially implemented}%

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

\command{bdist\_wininst} command. For example:

\begin{verbatim}

python setup.py bdist_wininst

\end{verbatim}

will create an executable installer, \file{Foo-1\_0.exe}, in the current

directory.

(Another way to create executable installers for Windows is with the

\command{bdist\_wise} command, which uses Wise---the commercial

installer-generator used to create Python's own installer---to create

the installer. Wise-based installers are more appropriate for large,

industrial-strength applications that need the full capabilities of a

``real'' installer. \command{bdist\_wininst} creates a self-extracting

zip file with a minimal user interface, which is enough for small- to

medium-sized module collections. You'll need to have version XXX of

Wise installed on your system for the \command{bdist\_wise} to work;

it's available from \url{http://foo/bar/baz}.)

Other \command{bdist} commands exist for other platforms: for example,

\command{bdist\_rpm} for RPM-based Linux systems, (\command{bdist\_deb})

for Debian-based Linux systems, and so forth. See

section~\ref{bdist-cmds} for details on all the \command{bdist}

commands.

\subsection{General Python terminology}

\label{python-terms}

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:

\begin{description}

\item[module] the basic unit of code reusability in Python: a block of

code imported by some other code. There are three types of modules

that concern us here: pure Python modules, extension modules, and

packages.

\item[pure Python module] a module written in Python and contained in a

single \file{.py} file (and possibly associated \file{.pyc} and/or

\file{.pyo} files). Sometimes referred to as a ``pure module.''

\item[extension module] a module written in the low-level language of

the Python implemention: C/C++ for CPython, Java for JPython.

Typically contained in a single dynamically loadable pre-compiled

file, e.g. a shared object (\file{.so}) file for CPython extensions on

Unix, a DLL (given the \file{.pyd} extension) for CPython extensions

on Windows, or a Java class file for JPython extensions.

\item[package] a module that contains other modules; typically contained

in a directory in the filesystem and distinguished from other

directories by the presence of a file \file{\_\_init\_\_.py}.

\item[root package] the root of the hierarchy of packages. (This isn't

really a package, since it doesn't have an \file{\_\_init\_\_.py}

file. But we have to call it something.) The vast majority of the

standard library is in the root package, as are many small, standalone

third-party modules that don't belong to a larger module collection.

Unlike regular packages, modules in the root package can be found in

many directories: in fact, every directory listed in \code{sys.path}

can contribute modules to the root package.

\end{description}

\subsection{Distutils-specific terminology}

\label{distutils-term}

The following terms apply more specifically to the domain of

distributing Python modules using the Distutils:

\begin{description}

\item[module distribution] a collection of Python modules distributed

together as a single downloadable resource and meant to be installed

\emph{en masse}. Examples of some well-known module distributions are

Numeric Python, PyXML, PIL (the Python Imaging Library), or

mxDateTime. (This would be called a \emph{package}, except that term

is already taken in the Python context: a single module distribution

may contain zero, one, or many Python packages.)

\item[pure module distribution] a module distribution that contains only

pure Python modules and packages. Sometimes referred to as a ``pure

distribution.''

\item[non-pure module distribution] a module distribution that contains

at least one extension module. Sometimes referred to as a ``non-pure

distribution.''

\item[distribution root] the top-level directory of your source tree (or

source distribution); the directory where \file{setup.py} exists and

is run from

\end{description}

\section{Writing the Setup Script}

\label{setup-script}

The setup script is the centre of all activity in building,

distributing, and installing modules using the Distutils. The main

purpose of the setup script is to describe your module distribution to

the Distutils, so that the various commands that operate on your modules

do the right thing. As we saw in section~\ref{simple-example} above,

the setup script consists mainly of a call to \function{setup()}, and

all information supplied to the Distutils is supplied as keyword

arguments to \function{setup()}.

Here's a slightly more involved example, which we'll follow for the next

couple of sections: the Distutils' own setup script. (Keep in mind that

although the Distutils are included with Python 1.6, they also have an

independent existence so that Python 1.5 users can use them to install

other module distributions. The Distutils' own setup script is used to

install the package into Python 1.5.)

\begin{verbatim}

#!/usr/bin/env python

from distutils.core import setup

setup (name = "Distutils",

version = "1.0",

description = "Python Module Distribution Utilities",

author = "Greg Ward",

author_email = "[email protected]",

url = "http://www.python.org/sigs/distutils-sig/",

packages = ['distutils', 'distutils.command'],

)

\end{verbatim}

There are only two differences between this and the trivial one-file

distribution presented in section~\ref{simple-example}: more

meta-data, and the specification of pure Python modules by package,

rather than by module. This is important since the Distutils consist of

a couple of dozen modules split into (so far) two packages; an explicit

list of every module would be tedious to generate and difficult to

maintain.

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 into 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 programmers should keep in

mind that the \emph{absence} of a leading slash indicates a relative

path, the opposite of the Mac OS convention with colons).

\subsection{Package directories}

\label{package-dirs}

The \option{packages} option tells the Distutils to process (build,

distribute, install, etc.) all pure Python modules found in each package

mentioned in the \option{packages} list. In order to do this, of

course, there has to be a correspondence between package names and

directories in the filesystem. The default correspondence is the most

obvious one, i.e. package \module{distutils} is found in the directory

\file{distutils} relative to the distribution root. Thus, when you say

\code{packages = ['foo']} in your setup script, you are promising that

the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might

be spelled differently on your system, but you get the idea) relative to

the directory where your setup script lives. (If you break this

promise, the Distutils will issue a warning but process the broken

package anyways.)

If you use a different convention to lay out your source directory,

that's no problem: you just have to supply the \option{package\_dir}

option to tell the Distutils about your convention. For example, say

you keep all Python source under \file{lib}, so that modules not in any

package are right in \file{lib}, modules in the \module{foo} package

are in \file{lib/foo}, and so forth. Then you would put

\begin{verbatim}

package_dir = {'': 'lib'}

\end{verbatim}

in your setup script. (The keys to this dictionary are package names,

and an empty package name stands for the ``root package,'' i.e. no

package at all. The values are directory names relative to your

distribution root.) In this case, when you say

\code{packages = ['foo']}, you are promising that the file

\file{lib/foo/\_\_init\_\_.py} exists.

Another possible convention is to put the \module{foo} package right in

\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This

would be written in the setup script as

\begin{verbatim}

package_dir = {'foo': 'lib'}

\end{verbatim}

A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}

dictionary implicitly applies to all packages below \var{package}, so

the \module{foo.bar} case is automatically handled here. In this

example, having \code{packages = ['foo', 'foo.bar']} tells the Distutils

to look for \file{lib/\_\_init\_\_.py} and

\file{lib/bar/\_\_init\_\_.py}. (Keep in mind that although

\option{package\_dir} applies recursively, you must explicitly list all

packages in \option{packages}: the Distutils will \emph{not} recursively

scan your source tree looking for any directory with an

\file{\_\_init\_\_.py} file.)

\subsection{Listing individual modules}

\label{listing-modules}

For a small module distribution, you might prefer to list all modules

rather than listing packages---especially the case of a single module

that goes in the ``root package'' (i.e., no package at all). This

simplest case was shown in section~\ref{simple-example}; here is a

slightly more involved example:

\begin{verbatim}

py_modules = ['mod1', 'pkg.mod2']

\end{verbatim}

This describes two modules, one of them in the ``root'' package, the

other in the \module{pkg} package. Again, the default package/directory

layout implies that these two modules can be found in \file{mod1.py} and

\file{pkg/mod2.py}, and that \file{pkg/\_\_init\_\_.py} exists as well.

And again, you can override the package/directory layout using the

\option{package\_dir} option.

\subsection{Describing extension modules}

\label{sec:describing-extensions}

\XXX{be sure to describe the whole \code{build\_info} dict, including

\code{extra\_compile\_args} and \code{extra\_link\_args}}

\section{Writing the Setup Configuration File}

\label{setup-config}

\XXX{not implemented yet!}

Often, it's not possible to write down everything needed to build a

distribution \emph{a priori}. You need to get some information from the

user, or from the user's system, in order to proceed. For example, you

might include an optional extension module that provides an interface to

a particular C library. If that library is installed on the user's

system, then you can build your optional extension---but you need to

know where to find the header and library file. If it's not installed,

you need to know this so you can omit your optional extension.

The preferred way to do this, of course, would be for you to tell the

Distutils which optional features (C libraries, system calls, external

utilities, etc.) you're looking for, and it would inspect the user's

system and try to find them. This functionality may appear in a future

version of the Distutils, but it isn't there now. So, for the time

being, we rely on the user building and installing your software to

provide the necessary information. The vehicle for doing so is the

setup configuration file, \file{setup.cfg}.

\XXX{need more here!}

\section{Creating a Source Distribution}

\label{source-dist}

As shown in section~\ref{simple-example}, you use the

\command{sdist} command to create a source distribution. In the

simplest case,

\begin{verbatim}

python setup.py sdist

\end{verbatim}

(assuming you haven't specified any \command{sdist} options in the setup

script or config file), \command{sdist} creates the the archive of the

default format for the current platform. The default formats are:

\begin{tableii}{ll}{textrm}%

{Platform}{Default archive format for source distributions}

\lineii{Unix}{gzipped tar file (\file{.tar.gz})}

\lineii{Windows}{zip file}

\end{tableii}

You can specify as many formats as you like using the

\longprogramopt{formats} option, for example:

\begin{verbatim}

python setup.py sdist --formats=gztar,zip

\end{verbatim}

to create a gzipped tarball and a zip file. The available formats 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})}{}

\end{tableiii}

\noindent Notes:

\begin{description}

\item[(1)] default on Windows

\item[(2)] default on Unix

\end{description}

\subsection{The manifest and manifest template}

\label{manifest}

Without any additional information, the \command{sdist} command puts a

minimal set of files into the source distribution:

\begin{itemize}

\item all Python source files implied by the \option{py\_modules} and

\option{packages} options

\item all C source files mentioned in the \option{ext\_modules} or

\option{libraries} options (\XXX{getting C library sources currently

broken -- no get\_source\_files() method in build\_clib.py!})

\item anything that looks like a test script: \file{test/test*.py}

(currently, the Distutils don't do anything with test scripts except

include them in source distributions, but in the future there will be

a standard for testing Python module distributions)

\item \file{README.txt} (or \file{README}) and \file{setup.py}

\end{itemize}

Sometimes this is enough, but usually you will want to specify

additional files to distribute. The typical way to do this is to write

a \emph{manifest template}, called \file{MANIFEST.in} by default. The

\command{sdist} command processes this template and generates a manifest

file, \file{MANIFEST}. (If you prefer, you can skip the manifest

template and generate the manifest yourself: it just lists one file per

line.)

The manifest template has one command per line, where each command

specifies a set of files to include or exclude from the source

distribution. For an example, again we turn to the Distutils' own

manifest template:

\begin{verbatim}

include *.txt

recursive-include examples *.txt *.py

prune examples/sample?/build

\end{verbatim}

The meanings should be fairly clear: include all files in the

distribution root matching \code{*.txt}, all files anywhere under the

\file{examples} directory matching \code{*.txt} or \code{*.py}, and

exclude all directories matching \code{examples/sample?/build}. There

are several other commands available in the manifest template

mini-language; see section~\ref{sdist-cmd}.

The order of commands in the manifest template very much matters:

initially, we have the list of default files as described above, and

each command in the template adds to or removes from that list of files.

When we have fully processed the manifest template, we have our complete

list of files. This list is written to the manifest for future

reference, and then used to build the source distribution archive(s).

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:

\begin{enumerate}

\item include all Python source files in the \file{distutils} and

\file{distutils/command} subdirectories (because packages

corresponding to those two directories were mentioned in the

\option{packages} option in the setup script)

\item include \file{test/test*.py} (always included)

\item include \file{README.txt} and \file{setup.py} (always included)

\item include \file{*.txt} in the distribution root (this will find

\file{README.txt} a second time, but such redundancies are weeded out

later)

\item in the sub-tree under \file{examples}, include anything matching

\file{*.txt}

\item in the sub-tree under \file{examples}, include anything matching

\file{*.py}

\item remove all files in the sub-trees starting at directories matching

\file{examples/sample?/build}---this may exclude files included by the

previous two steps, so it's important that the \code{prune} command in

the manifest template comes after the two \code{recursive-include}

commands

\end{enumerate}

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.

\subsection{Manifest-related options}

\label{manifest-options}

The normal course of operations for the \command{sdist} command is as

follows:

\begin{itemize}

\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}

\item use the list of files now in \file{MANIFEST} (either just

generated or read in) to create the source distribution archive(s)

\end{itemize}

There are a couple of options that modify this behaviour.

First, you might want to force the manifest to be regenerated---for

example, if you have added or removed files or directories that match an

existing pattern in the manifest template, you should regenerate the

manifest:

\begin{verbatim}

python setup.py sdist --force-manifest

\end{verbatim}

\XXX{this is stupid, but is there a better way to do it without

reprocessing MANIFEST.in every single bloody time?}

Or, you might just want to (re)generate the manifest, but not create a

source distribution:

\begin{verbatim}

python setup.py sdist --manifest-only

\end{verbatim}

(\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.)

If you don't want to use the default file set, you can supply the

\longprogramopt{no-defaults} option. If you use

\longprogramopt{no-defaults} and don't supply a manifest template (or

it's empty, or nothing matches the patterns in it), then your source

distribution will be empty.

\section{Creating Built Distributions}

\label{built-dist}

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}

python setup.py bdist

\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 \longprogramopt{format} option,

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

formats to generate: for example,

\begin{verbatim}

python setup.py bdist --format=zip

\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

\longprogramopt{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}

\section{Examples}

\label{examples}

\subsection{Pure Python distribution (by module)}

\label{pure-mod}

\subsection{Pure Python distribution (by package)}

\label{pure-pkg}

\subsection{Single extension module}

\label{single-ext}

\subsection{Multiple extension modules}

\label{multiple-ext}

\subsection{Putting it all together}

\section{Extending the Distutils}

\label{extending}

\subsection{Extending existing commands}

\label{extend-existing}

\subsection{Writing new commands}

\label{new-commands}

\section{Reference}

\label{ref}

\subsection{Building modules: the \protect\command{build} command family}

\label{build-cmds}

\subsubsection{\protect\command{build}}

\label{build-cmd}

\subsubsection{\protect\command{build\_py}}

\label{build-py-cmd}

\subsubsection{\protect\command{build\_ext}}

\label{build-ext-cmd}

\subsubsection{\protect\command{build\_clib}}

\label{build-clib-cmd}

\subsection{Installing modules: the \protect\command{install} command family}

\label{install-cmd}

The install command ensures that the build commands have been run and then

runs the subcommands \command{install\_lib},

\command{install\_data} and

\command{install\_scripts}.

\subsubsection{\protect\command{install\_lib}}

\label{sec:install-lib-cmd}

\subsubsection{\protect\command{install\_data}}

\label{sec:install-data-cmd}

This command installs all data files provided with the distribution.

\subsubsection{\protect\command{install\_scripts}}

\label{sec:install-scripts-cmd}

This command installs all (Python) scripts in the distribution.

\subsection{Cleaning up: the \protect\command{clean} command}

\label{clean-cmd}

\subsection{Creating a source distribution: the \protect\command{sdist} command}

\label{sdist-cmd}

\XXX{fragment moved down from above: needs context!}

The manifest template commands are:

\begin{tableii}{ll}{command}{Command}{Description}

\lineii{include \var{pat1} \var{pat2} ... }

{include all files matching any of the listed patterns}

\lineii{exclude \var{pat1} \var{pat2} ... }

{exclude all files matching any of the listed patterns}

\lineii{recursive-include \var{dir} \var{pat1} \var{pat2} ... }

{include all files under \var{dir} matching any of the listed patterns}

\lineii{recursive-exclude \var{dir} \var{pat1} \var{pat2} ...}

{exclude all files under \var{dir} matching any of the listed patterns}

\lineii{global-include \var{pat1} \var{pat2} ...}

{include all files anywhere in the source tree matching

any of the listed patterns}

\lineii{global-exclude \var{pat1} \var{pat2} ...}

{exclude all files anywhere in the source tree matching

any of the listed patterns}

\lineii{prune \var{dir}}{exclude all files under \var{dir}}

\lineii{graft \var{dir}}{include all files under \var{dir}}

\end{tableii}

The patterns here are Unix-style ``glob'' patterns: \code{*} matches any

sequence of regular filename characters, \code{?} matches any single

regular filename character, and \code{[\var{range}]} matches any of the

characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},

\code{a-f0-9\_.}). The definition of ``regular filename character'' is

platform-specific: on Unix it is anything except slash; on Windows

anything except backslash or colon; on Mac OS anything except colon.

\XXX{Windows and Mac OS support not there yet}

\subsection{Creating a ``built'' distribution: the

\protect\command{bdist} command family}

\label{bdist-cmds}

\subsubsection{\protect\command{blib}}

\subsubsection{\protect\command{blib\_dumb}}

\subsubsection{\protect\command{blib\_rpm}}

\subsubsection{\protect\command{blib\_wise}}

\end{document}