blob: b06d88a7c9cfc5142f3df23ad16b21b6b1fbf945 [file] [log] [blame]
Greg Wardabc52162000-02-26 00:52:48 +00001\documentclass{howto}
Greg Ward16aafcd2000-04-09 04:06:44 +00002\usepackage{distutils}
Greg Wardabc52162000-02-26 00:52:48 +00003
Greg Wardb6528972000-09-07 02:40:37 +00004% $Id$
5
Greg Ward16aafcd2000-04-09 04:06:44 +00006\title{Distributing Python Modules}
Greg Wardabc52162000-02-26 00:52:48 +00007
Greg Wardabc52162000-02-26 00:52:48 +00008\author{Greg Ward}
Fred Drake17f690f2001-07-14 02:14:42 +00009\authoraddress{Email: \email{gward@python.net}}
Greg Wardabc52162000-02-26 00:52:48 +000010
Greg Warde3cca262000-08-31 16:36:31 +000011\makeindex
Greg Ward16aafcd2000-04-09 04:06:44 +000012
Greg Wardabc52162000-02-26 00:52:48 +000013\begin{document}
14
Greg Wardfacb8db2000-04-09 04:32:40 +000015\maketitle
Greg Warde3cca262000-08-31 16:36:31 +000016\begin{abstract}
17 \noindent
18 This document describes the Python Distribution Utilities
19 (``Distutils'') from the module developer's point-of-view, describing
20 how to use the Distutils to make Python modules and extensions easily
21 available to a wider audience with very little overhead for
22 build/release/install mechanics.
23\end{abstract}
24
Fred Drakea09262e2001-03-01 18:35:43 +000025% The ugly "%begin{latexonly}" pseudo-environment supresses the table
26% of contents for HTML generation.
27%
28%begin{latexonly}
Greg Wardfacb8db2000-04-09 04:32:40 +000029\tableofcontents
Fred Drakea09262e2001-03-01 18:35:43 +000030%end{latexonly}
31
Greg Ward16aafcd2000-04-09 04:06:44 +000032
33\section{Introduction}
Greg Warde78298a2000-04-28 17:12:24 +000034\label{intro}
Greg Ward16aafcd2000-04-09 04:06:44 +000035
36In the past, Python module developers have not had much infrastructure
37support for distributing modules, nor have Python users had much support
38for installing and maintaining third-party modules. With the
39introduction of the Python Distribution Utilities (Distutils for short)
Greg Ward1d8f57a2000-08-05 00:43:11 +000040in Python 1.6, this situation should start to improve.
Greg Ward16aafcd2000-04-09 04:06:44 +000041
42This document only covers using the Distutils to distribute your Python
Greg Ward1d8f57a2000-08-05 00:43:11 +000043modules. Using the Distutils does not tie you to Python 1.6, though:
44the Distutils work just fine with Python 1.5.2, and it is reasonable
45(and expected to become commonplace) to expect users of Python 1.5.2 to
Greg Ward16aafcd2000-04-09 04:06:44 +000046download and install the Distutils separately before they can install
Greg Ward1d8f57a2000-08-05 00:43:11 +000047your modules. Python 1.6 (or later) users, of course, won't have to add
48anything to their Python installation in order to use the Distutils to
49install third-party modules.
Greg Ward16aafcd2000-04-09 04:06:44 +000050
51This document concentrates on the role of developer/distributor: if
Fred Drake01df4532000-06-30 03:36:41 +000052you're looking for information on installing Python modules, you
53should refer to the \citetitle[../inst/inst.html]{Installing Python
54Modules} manual.
Greg Ward16aafcd2000-04-09 04:06:44 +000055
56
Greg Wardfacb8db2000-04-09 04:32:40 +000057\section{Concepts \& Terminology}
Greg Warde78298a2000-04-28 17:12:24 +000058\label{concepts}
Greg Ward16aafcd2000-04-09 04:06:44 +000059
60Using the Distutils is quite simple, both for module developers and for
61users/administrators installing third-party modules. As a developer,
Thomas Heller5f52f722001-02-19 17:48:03 +000062your responsibilities (apart from writing solid, well-documented and
Greg Ward16aafcd2000-04-09 04:06:44 +000063well-tested code, of course!) are:
64\begin{itemize}
65\item write a setup script (\file{setup.py} by convention)
66\item (optional) write a setup configuration file
67\item create a source distribution
68\item (optional) create one or more built (binary) distributions
69\end{itemize}
70Each of these tasks is covered in this document.
71
72Not all module developers have access to a multitude of platforms, so
73it's not always feasible to expect them to create a multitude of built
74distributions. It is hoped that a class of intermediaries, called
Greg Ward19c67f82000-06-24 01:33:16 +000075\emph{packagers}, will arise to address this need. Packagers will take
76source distributions released by module developers, build them on one or
77more platforms, and release the resulting built distributions. Thus,
78users on the most popular platforms will be able to install most popular
79Python module distributions in the most natural way for their platform,
80without having to run a single setup script or compile a line of code.
Greg Ward16aafcd2000-04-09 04:06:44 +000081
82
83\subsection{A simple example}
Greg Warde78298a2000-04-28 17:12:24 +000084\label{simple-example}
Greg Ward16aafcd2000-04-09 04:06:44 +000085
86The setup script is usually quite simple, although since it's written in
Greg Ward47f99a62000-09-04 20:07:15 +000087Python, there are no arbitrary limits to what you can do with
88it.\footnote{But be careful about putting arbitrarily expensive
89 operations in your setup script; unlike, say, Autoconf-style configure
90 scripts, the setup script may be run multiple times in the course of
91 building and installing your module distribution. If you need to
92 insert potentially expensive processing steps into the Distutils
93 chain, see section~\ref{extending} on extending the Distutils.} If
Greg Ward1d8f57a2000-08-05 00:43:11 +000094all you want to do is distribute a module called \module{foo}, contained
95in a file \file{foo.py}, then your setup script can be as little as
96this:
Fred Drakea09262e2001-03-01 18:35:43 +000097
Greg Ward16aafcd2000-04-09 04:06:44 +000098\begin{verbatim}
99from distutils.core import setup
Fred Drakea09262e2001-03-01 18:35:43 +0000100setup(name="foo",
101 version="1.0",
102 py_modules=["foo"])
Greg Ward16aafcd2000-04-09 04:06:44 +0000103\end{verbatim}
Greg Ward370248d2000-06-24 01:45:47 +0000104
Greg Ward16aafcd2000-04-09 04:06:44 +0000105Some observations:
106\begin{itemize}
Greg Ward370248d2000-06-24 01:45:47 +0000107\item most information that you supply to the Distutils is supplied as
Greg Wardfacb8db2000-04-09 04:32:40 +0000108 keyword arguments to the \function{setup()} function
Greg Ward16aafcd2000-04-09 04:06:44 +0000109\item those keyword arguments fall into two categories: package
110 meta-data (name, version number) and information about what's in the
Greg Ward370248d2000-06-24 01:45:47 +0000111 package (a list of pure Python modules, in this case)
Greg Ward16aafcd2000-04-09 04:06:44 +0000112\item modules are specified by module name, not filename (the same will
113 hold true for packages and extensions)
114\item it's recommended that you supply a little more meta-data, in
115 particular your name, email address and a URL for the project
Greg Ward47f99a62000-09-04 20:07:15 +0000116 (see section~\ref{setup-script} for an example)
Greg Ward16aafcd2000-04-09 04:06:44 +0000117\end{itemize}
118
Greg Ward370248d2000-06-24 01:45:47 +0000119To create a source distribution for this module, you would create a
120setup script, \file{setup.py}, containing the above code, and run:
Fred Drakea09262e2001-03-01 18:35:43 +0000121
Greg Ward16aafcd2000-04-09 04:06:44 +0000122\begin{verbatim}
123python setup.py sdist
124\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000125
Fred Drakeeff9a872000-10-26 16:41:03 +0000126which will create an archive file (e.g., tarball on \UNIX, ZIP file on
Greg Ward16aafcd2000-04-09 04:06:44 +0000127Windows) containing your setup script, \file{setup.py}, and your module,
128\file{foo.py}. The archive file will be named \file{Foo-1.0.tar.gz} (or
129\file{.zip}), and will unpack into a directory \file{Foo-1.0}.
130
131If an end-user wishes to install your \module{foo} module, all she has
Greg Ward59d382e2000-05-26 01:04:47 +0000132to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it,
Greg Ward16aafcd2000-04-09 04:06:44 +0000133and---from the \file{Foo-1.0} directory---run
Fred Drakea09262e2001-03-01 18:35:43 +0000134
Greg Ward16aafcd2000-04-09 04:06:44 +0000135\begin{verbatim}
136python setup.py install
137\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000138
Greg Ward16aafcd2000-04-09 04:06:44 +0000139which will ultimately copy \file{foo.py} to the appropriate directory
140for third-party modules in their Python installation.
141
142This simple example demonstrates some fundamental concepts of the
143Distutils: first, both developers and installers have the same basic
144user interface, i.e. the setup script. The difference is which
145Distutils \emph{commands} they use: the \command{sdist} command is
146almost exclusively for module developers, while \command{install} is
147more often for installers (although most developers will want to install
148their own code occasionally).
149
Greg Ward16aafcd2000-04-09 04:06:44 +0000150If you want to make things really easy for your users, you can create
151one or more built distributions for them. For instance, if you are
152running on a Windows machine, and want to make things easy for other
153Windows users, you can create an executable installer (the most
154appropriate type of built distribution for this platform) with the
Greg Ward59d382e2000-05-26 01:04:47 +0000155\command{bdist\_wininst} command. For example:
Fred Drakea09262e2001-03-01 18:35:43 +0000156
Greg Ward16aafcd2000-04-09 04:06:44 +0000157\begin{verbatim}
Greg Ward59d382e2000-05-26 01:04:47 +0000158python setup.py bdist_wininst
Greg Ward16aafcd2000-04-09 04:06:44 +0000159\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000160
Greg Ward1d8f57a2000-08-05 00:43:11 +0000161will create an executable installer, \file{Foo-1.0.win32.exe}, in the
162current directory.
Greg Ward16aafcd2000-04-09 04:06:44 +0000163
Thomas Heller5f52f722001-02-19 17:48:03 +0000164Currently (Distutils 0.9.2), the only other useful built
Greg Ward1d8f57a2000-08-05 00:43:11 +0000165distribution format is RPM, implemented by the \command{bdist\_rpm}
166command. For example, the following command will create an RPM file
167called \file{Foo-1.0.noarch.rpm}:
Fred Drakea09262e2001-03-01 18:35:43 +0000168
Greg Ward1d8f57a2000-08-05 00:43:11 +0000169\begin{verbatim}
170python setup.py bdist_rpm
171\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000172
Greg Ward1d8f57a2000-08-05 00:43:11 +0000173(This uses the \command{rpm} command, so has to be run on an RPM-based
174system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
175
176You can find out what distribution formats are available at any time by
177running
Fred Drakea09262e2001-03-01 18:35:43 +0000178
Greg Ward1d8f57a2000-08-05 00:43:11 +0000179\begin{verbatim}
180python setup.py bdist --help-formats
181\end{verbatim}
Greg Ward16aafcd2000-04-09 04:06:44 +0000182
183
184\subsection{General Python terminology}
Greg Warde78298a2000-04-28 17:12:24 +0000185\label{python-terms}
Greg Ward16aafcd2000-04-09 04:06:44 +0000186
187If you're reading this document, you probably have a good idea of what
188modules, extensions, and so forth are. Nevertheless, just to be sure
189that everyone is operating from a common starting point, we offer the
190following glossary of common Python terms:
191\begin{description}
192\item[module] the basic unit of code reusability in Python: a block of
Greg Ward1d8f57a2000-08-05 00:43:11 +0000193 code imported by some other code. Three types of modules concern us
194 here: pure Python modules, extension modules, and packages.
Greg Ward16aafcd2000-04-09 04:06:44 +0000195\item[pure Python module] a module written in Python and contained in a
196 single \file{.py} file (and possibly associated \file{.pyc} and/or
197 \file{.pyo} files). Sometimes referred to as a ``pure module.''
198\item[extension module] a module written in the low-level language of
Thomas Heller5f52f722001-02-19 17:48:03 +0000199 the Python implementation: C/C++ for Python, Java for JPython.
Greg Ward16aafcd2000-04-09 04:06:44 +0000200 Typically contained in a single dynamically loadable pre-compiled
Fred Drakeeff9a872000-10-26 16:41:03 +0000201 file, e.g. a shared object (\file{.so}) file for Python extensions on
202 \UNIX, a DLL (given the \file{.pyd} extension) for Python extensions
Greg Ward1bbe3292000-06-25 03:14:13 +0000203 on Windows, or a Java class file for JPython extensions. (Note that
Fred Drakeeff9a872000-10-26 16:41:03 +0000204 currently, the Distutils only handles C/C++ extensions for Python.)
Greg Ward16aafcd2000-04-09 04:06:44 +0000205\item[package] a module that contains other modules; typically contained
206 in a directory in the filesystem and distinguished from other
207 directories by the presence of a file \file{\_\_init\_\_.py}.
Greg Ward6153fa12000-05-26 02:24:28 +0000208\item[root package] the root of the hierarchy of packages. (This isn't
209 really a package, since it doesn't have an \file{\_\_init\_\_.py}
210 file. But we have to call it something.) The vast majority of the
211 standard library is in the root package, as are many small, standalone
212 third-party modules that don't belong to a larger module collection.
213 Unlike regular packages, modules in the root package can be found in
214 many directories: in fact, every directory listed in \code{sys.path}
215 can contribute modules to the root package.
Greg Ward16aafcd2000-04-09 04:06:44 +0000216\end{description}
217
218
219\subsection{Distutils-specific terminology}
Greg Warde78298a2000-04-28 17:12:24 +0000220\label{distutils-term}
Greg Ward16aafcd2000-04-09 04:06:44 +0000221
222The following terms apply more specifically to the domain of
223distributing Python modules using the Distutils:
224\begin{description}
225\item[module distribution] a collection of Python modules distributed
226 together as a single downloadable resource and meant to be installed
227 \emph{en masse}. Examples of some well-known module distributions are
228 Numeric Python, PyXML, PIL (the Python Imaging Library), or
229 mxDateTime. (This would be called a \emph{package}, except that term
Greg Ward59d382e2000-05-26 01:04:47 +0000230 is already taken in the Python context: a single module distribution
231 may contain zero, one, or many Python packages.)
Greg Ward16aafcd2000-04-09 04:06:44 +0000232\item[pure module distribution] a module distribution that contains only
233 pure Python modules and packages. Sometimes referred to as a ``pure
234 distribution.''
235\item[non-pure module distribution] a module distribution that contains
236 at least one extension module. Sometimes referred to as a ``non-pure
237 distribution.''
238\item[distribution root] the top-level directory of your source tree (or
239 source distribution); the directory where \file{setup.py} exists and
240 is run from
241\end{description}
242
243
244\section{Writing the Setup Script}
Greg Warde78298a2000-04-28 17:12:24 +0000245\label{setup-script}
Greg Ward16aafcd2000-04-09 04:06:44 +0000246
247The setup script is the centre of all activity in building,
248distributing, and installing modules using the Distutils. The main
249purpose of the setup script is to describe your module distribution to
Greg Wardd5767a52000-04-19 22:48:09 +0000250the Distutils, so that the various commands that operate on your modules
Greg Ward59d382e2000-05-26 01:04:47 +0000251do the right thing. As we saw in section~\ref{simple-example} above,
252the setup script consists mainly of a call to \function{setup()}, and
Greg Ward1bbe3292000-06-25 03:14:13 +0000253most information supplied to the Distutils by the module developer is
254supplied as keyword arguments to \function{setup()}.
Greg Ward16aafcd2000-04-09 04:06:44 +0000255
256Here's a slightly more involved example, which we'll follow for the next
257couple of sections: the Distutils' own setup script. (Keep in mind that
Greg Ward1d8f57a2000-08-05 00:43:11 +0000258although the Distutils are included with Python 1.6 and later, they also
259have an independent existence so that Python 1.5.2 users can use them to
260install other module distributions. The Distutils' own setup script,
261shown here, is used to install the package into Python 1.5.2.)
Greg Ward16aafcd2000-04-09 04:06:44 +0000262
263\begin{verbatim}
264#!/usr/bin/env python
265
266from distutils.core import setup
267
Fred Drakea09262e2001-03-01 18:35:43 +0000268setup(name="Distutils",
269 version="1.0",
270 description="Python Distribution Utilities",
271 author="Greg Ward",
272 author_email="gward@python.net",
273 url="http://www.python.org/sigs/distutils-sig/",
274 packages=['distutils', 'distutils.command'],
275 )
Greg Ward16aafcd2000-04-09 04:06:44 +0000276\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000277
Greg Ward16aafcd2000-04-09 04:06:44 +0000278There are only two differences between this and the trivial one-file
Greg Warde78298a2000-04-28 17:12:24 +0000279distribution presented in section~\ref{simple-example}: more
Greg Ward16aafcd2000-04-09 04:06:44 +0000280meta-data, and the specification of pure Python modules by package,
281rather than by module. This is important since the Distutils consist of
282a couple of dozen modules split into (so far) two packages; an explicit
283list of every module would be tedious to generate and difficult to
284maintain.
285
Greg Ward46b98e32000-04-14 01:53:36 +0000286Note that any pathnames (files or directories) supplied in the setup
Fred Drakeeff9a872000-10-26 16:41:03 +0000287script should be written using the \UNIX{} convention, i.e.
Greg Ward46b98e32000-04-14 01:53:36 +0000288slash-separated. The Distutils will take care of converting this
Greg Ward59d382e2000-05-26 01:04:47 +0000289platform-neutral representation into whatever is appropriate on your
Greg Ward46b98e32000-04-14 01:53:36 +0000290current platform before actually using the pathname. This makes your
291setup script portable across operating systems, which of course is one
292of the major goals of the Distutils. In this spirit, all pathnames in
Fred Drakeeff9a872000-10-26 16:41:03 +0000293this document are slash-separated (MacOS programmers should keep in
Greg Ward59d382e2000-05-26 01:04:47 +0000294mind that the \emph{absence} of a leading slash indicates a relative
Fred Drakeeff9a872000-10-26 16:41:03 +0000295path, the opposite of the MacOS convention with colons).
Greg Ward46b98e32000-04-14 01:53:36 +0000296
Thomas Heller5f52f722001-02-19 17:48:03 +0000297This, of course, only applies to pathnames given to Distutils functions.
298If you, for example, use standard python functions such as glob.glob
299or os.listdir to specify files, you should be careful to write portable
300code instead of hardcoding path separators:
Fred Drakea09262e2001-03-01 18:35:43 +0000301
Thomas Heller5f52f722001-02-19 17:48:03 +0000302\begin{verbatim}
303 glob.glob(os.path.join('mydir', 'subdir', '*.html'))
304 os.listdir(os.path.join('mydir', 'subdir'))
305\end{verbatim}
Greg Ward16aafcd2000-04-09 04:06:44 +0000306
Greg Ward2afffd42000-08-06 20:37:24 +0000307\subsection{Listing whole packages}
308\label{listing-packages}
Greg Ward16aafcd2000-04-09 04:06:44 +0000309
310The \option{packages} option tells the Distutils to process (build,
311distribute, install, etc.) all pure Python modules found in each package
312mentioned in the \option{packages} list. In order to do this, of
313course, there has to be a correspondence between package names and
314directories in the filesystem. The default correspondence is the most
Greg Ward1ecc2512000-04-19 22:36:24 +0000315obvious one, i.e. package \module{distutils} is found in the directory
Greg Ward16aafcd2000-04-09 04:06:44 +0000316\file{distutils} relative to the distribution root. Thus, when you say
317\code{packages = ['foo']} in your setup script, you are promising that
318the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might
319be spelled differently on your system, but you get the idea) relative to
320the directory where your setup script lives. (If you break this
321promise, the Distutils will issue a warning but process the broken
322package anyways.)
323
324If you use a different convention to lay out your source directory,
325that's no problem: you just have to supply the \option{package\_dir}
326option to tell the Distutils about your convention. For example, say
Greg Ward1d8f57a2000-08-05 00:43:11 +0000327you keep all Python source under \file{lib}, so that modules in the
328``root package'' (i.e., not in any package at all) are right in
329\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
330and so forth. Then you would put
Fred Drakea09262e2001-03-01 18:35:43 +0000331
Greg Ward16aafcd2000-04-09 04:06:44 +0000332\begin{verbatim}
333package_dir = {'': 'lib'}
334\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000335
Greg Ward16aafcd2000-04-09 04:06:44 +0000336in your setup script. (The keys to this dictionary are package names,
Greg Ward1d8f57a2000-08-05 00:43:11 +0000337and an empty package name stands for the root package. The values are
338directory names relative to your distribution root.) In this case, when
339you say \code{packages = ['foo']}, you are promising that the file
Greg Ward16aafcd2000-04-09 04:06:44 +0000340\file{lib/foo/\_\_init\_\_.py} exists.
341
Greg Ward1ecc2512000-04-19 22:36:24 +0000342Another possible convention is to put the \module{foo} package right in
343\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This
Greg Ward16aafcd2000-04-09 04:06:44 +0000344would be written in the setup script as
Fred Drakea09262e2001-03-01 18:35:43 +0000345
Greg Ward16aafcd2000-04-09 04:06:44 +0000346\begin{verbatim}
347package_dir = {'foo': 'lib'}
348\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000349
Greg Ward59d382e2000-05-26 01:04:47 +0000350A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
351dictionary implicitly applies to all packages below \var{package}, so
352the \module{foo.bar} case is automatically handled here. In this
353example, having \code{packages = ['foo', 'foo.bar']} tells the Distutils
354to look for \file{lib/\_\_init\_\_.py} and
355\file{lib/bar/\_\_init\_\_.py}. (Keep in mind that although
356\option{package\_dir} applies recursively, you must explicitly list all
357packages in \option{packages}: the Distutils will \emph{not} recursively
358scan your source tree looking for any directory with an
359\file{\_\_init\_\_.py} file.)
Greg Ward16aafcd2000-04-09 04:06:44 +0000360
361
362\subsection{Listing individual modules}
Greg Warde78298a2000-04-28 17:12:24 +0000363\label{listing-modules}
Greg Ward16aafcd2000-04-09 04:06:44 +0000364
365For a small module distribution, you might prefer to list all modules
366rather than listing packages---especially the case of a single module
367that goes in the ``root package'' (i.e., no package at all). This
Greg Warde78298a2000-04-28 17:12:24 +0000368simplest case was shown in section~\ref{simple-example}; here is a
Greg Ward16aafcd2000-04-09 04:06:44 +0000369slightly more involved example:
Fred Drakea09262e2001-03-01 18:35:43 +0000370
Greg Ward16aafcd2000-04-09 04:06:44 +0000371\begin{verbatim}
372py_modules = ['mod1', 'pkg.mod2']
373\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000374
Greg Ward16aafcd2000-04-09 04:06:44 +0000375This describes two modules, one of them in the ``root'' package, the
Greg Wardd5767a52000-04-19 22:48:09 +0000376other in the \module{pkg} package. Again, the default package/directory
377layout implies that these two modules can be found in \file{mod1.py} and
378\file{pkg/mod2.py}, and that \file{pkg/\_\_init\_\_.py} exists as well.
Greg Ward2afffd42000-08-06 20:37:24 +0000379And again, you can override the package/directory correspondence using
380the \option{package\_dir} option.
Greg Ward59d382e2000-05-26 01:04:47 +0000381
382
383\subsection{Describing extension modules}
Greg Ward1365a302000-08-31 14:47:05 +0000384\label{describing-extensions}
Greg Ward59d382e2000-05-26 01:04:47 +0000385
Greg Ward2afffd42000-08-06 20:37:24 +0000386Just as writing Python extension modules is a bit more complicated than
387writing pure Python modules, describing them to the Distutils is a bit
388more complicated. Unlike pure modules, it's not enough just to list
389modules or packages and expect the Distutils to go out and find the
390right files; you have to specify the extension name, source file(s), and
391any compile/link requirements (include directories, libraries to link
392with, etc.).
393
394All of this is done through another keyword argument to
395\function{setup()}, the \option{extensions} option. \option{extensions}
396is just a list of \class{Extension} instances, each of which describes a
397single extension module. Suppose your distribution includes a single
398extension, called \module{foo} and implemented by \file{foo.c}. If no
399additional instructions to the compiler/linker are needed, describing
400this extension is quite simple:
Fred Drakea09262e2001-03-01 18:35:43 +0000401
Greg Ward2afffd42000-08-06 20:37:24 +0000402\begin{verbatim}
403Extension("foo", ["foo.c"])
404\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000405
Greg Ward2afffd42000-08-06 20:37:24 +0000406The \class{Extension} class can be imported from
407\module{distutils.core}, along with \function{setup()}. Thus, the setup
408script for a module distribution that contains only this one extension
409and nothing else might be:
Fred Drakea09262e2001-03-01 18:35:43 +0000410
Greg Ward2afffd42000-08-06 20:37:24 +0000411\begin{verbatim}
412from distutils.core import setup, Extension
Fred Drakea09262e2001-03-01 18:35:43 +0000413setup(name="foo", version="1.0",
414 ext_modules=[Extension("foo", ["foo.c"])])
Greg Ward2afffd42000-08-06 20:37:24 +0000415\end{verbatim}
416
417The \class{Extension} class (actually, the underlying extension-building
Andrew M. Kuchlingda23c4f2001-02-17 00:38:48 +0000418machinery implemented by the \command{build\_ext} command) supports a
Greg Ward2afffd42000-08-06 20:37:24 +0000419great deal of flexibility in describing Python extensions, which is
420explained in the following sections.
421
422
423\subsubsection{Extension names and packages}
424
425The first argument to the \class{Extension} constructor is always the
426name of the extension, including any package names. For example,
Fred Drakea09262e2001-03-01 18:35:43 +0000427
Greg Ward2afffd42000-08-06 20:37:24 +0000428\begin{verbatim}
429Extension("foo", ["src/foo1.c", "src/foo2.c"])
430\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000431
Greg Ward2afffd42000-08-06 20:37:24 +0000432describes an extension that lives in the root package, while
Fred Drakea09262e2001-03-01 18:35:43 +0000433
Greg Ward2afffd42000-08-06 20:37:24 +0000434\begin{verbatim}
435Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])
436\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000437
Greg Ward2afffd42000-08-06 20:37:24 +0000438describes the same extension in the \module{pkg} package. The source
439files and resulting object code are identical in both cases; the only
440difference is where in the filesystem (and therefore where in Python's
441namespace hierarchy) the resulting extension lives.
442
443If you have a number of extensions all in the same package (or all under
444the same base package), use the \option{ext\_package} keyword argument
445to \function{setup()}. For example,
Fred Drakea09262e2001-03-01 18:35:43 +0000446
Greg Ward2afffd42000-08-06 20:37:24 +0000447\begin{verbatim}
448setup(...
Fred Drakea09262e2001-03-01 18:35:43 +0000449 ext_package="pkg",
450 ext_modules=[Extension("foo", ["foo.c"]),
451 Extension("subpkg.bar", ["bar.c"])]
Greg Ward2afffd42000-08-06 20:37:24 +0000452 )
453\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000454
Greg Ward2afffd42000-08-06 20:37:24 +0000455will compile \file{foo.c} to the extension \module{pkg.foo}, and
456\file{bar.c} to \module{pkg.subpkg.bar}.
457
458
459\subsubsection{Extension source files}
460
461The second argument to the \class{Extension} constructor is a list of
462source files. Since the Distutils currently only support C/C++
463extensions, these are normally C/C++ source files. (Be sure to use
464appropriate extensions to distinguish C++ source files: \file{.cc} and
Fred Drakeeff9a872000-10-26 16:41:03 +0000465\file{.cpp} seem to be recognized by both \UNIX{} and Windows compilers.)
Greg Ward2afffd42000-08-06 20:37:24 +0000466
467However, you can also include SWIG interface (\file{.i}) files in the
468list; the \command{build\_ext} command knows how to deal with SWIG
469extensions: it will run SWIG on the interface file and compile the
470resulting C/C++ file into your extension.
471
472\XXX{SWIG support is rough around the edges and largely untested;
473 especially SWIG support of C++ extensions! Explain in more detail
474 here when the interface firms up.}
475
476On some platforms, you can include non-source files that are processed
477by the compiler and included in your extension. Currently, this just
Thomas Heller5f52f722001-02-19 17:48:03 +0000478means Windows message text (\file{.mc}) files and resource definition
479(\file{.rc}) files for Visual C++. These will be compiled to binary resource
480(\file{.res}) files and linked into the executable.
Greg Ward2afffd42000-08-06 20:37:24 +0000481
482
483\subsubsection{Preprocessor options}
484
485Three optional arguments to \class{Extension} will help if you need to
486specify include directories to search or preprocessor macros to
487define/undefine: \code{include\_dirs}, \code{define\_macros}, and
488\code{undef\_macros}.
489
490For example, if your extension requires header files in the
491\file{include} directory under your distribution root, use the
492\code{include\_dirs} option:
Fred Drakea09262e2001-03-01 18:35:43 +0000493
Greg Ward2afffd42000-08-06 20:37:24 +0000494\begin{verbatim}
495Extension("foo", ["foo.c"], include_dirs=["include"])
496\end{verbatim}
497
498You can specify absolute directories there; if you know that your
Fred Drakeeff9a872000-10-26 16:41:03 +0000499extension will only be built on \UNIX{} systems with X11R6 installed to
Greg Ward2afffd42000-08-06 20:37:24 +0000500\file{/usr}, you can get away with
Fred Drakea09262e2001-03-01 18:35:43 +0000501
Greg Ward2afffd42000-08-06 20:37:24 +0000502\begin{verbatim}
503Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])
504\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000505
Greg Ward2afffd42000-08-06 20:37:24 +0000506You should avoid this sort of non-portable usage if you plan to
507distribute your code: it's probably better to write your code to include
508(e.g.) \code{<X11/Xlib.h>}.
509
510If you need to include header files from some other Python extension,
511you can take advantage of the fact that the Distutils install extension
512header files in a consistent way. For example, the Numerical Python
Fred Drakeeff9a872000-10-26 16:41:03 +0000513header files are installed (on a standard \UNIX{} installation) to
Greg Ward2afffd42000-08-06 20:37:24 +0000514\file{/usr/local/include/python1.5/Numerical}. (The exact location will
515differ according to your platform and Python installation.) Since the
516Python include directory---\file{/usr/local/include/python1.5} in this
517case---is always included in the search path when building Python
518extensions, the best approach is to include (e.g.)
519\code{<Numerical/arrayobject.h>}. If you insist on putting the
520\file{Numerical} include directory right into your header search path,
521though, you can find that directory using the Distutils
522\module{sysconfig} module:
Fred Drakea09262e2001-03-01 18:35:43 +0000523
Greg Ward2afffd42000-08-06 20:37:24 +0000524\begin{verbatim}
525from distutils.sysconfig import get_python_inc
526incdir = os.path.join(get_python_inc(plat_specific=1), "Numerical")
527setup(...,
528 Extension(..., include_dirs=[incdir]))
529\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000530
Greg Ward2afffd42000-08-06 20:37:24 +0000531Even though this is quite portable---it will work on any Python
532installation, regardless of platform---it's probably easier to just
533write your C code in the sensible way.
534
535You can define and undefine pre-processor macros with the
536\code{define\_macros} and \code{undef\_macros} options.
537\code{define\_macros} takes a list of \code{(name, value)} tuples, where
538\code{name} is the name of the macro to define (a string) and
539\code{value} is its value: either a string or \code{None}. (Defining a
540macro \code{FOO} to \code{None} is the equivalent of a bare
541\code{\#define FOO} in your C source: with most compilers, this sets
542\code{FOO} to the string \code{1}.) \code{undef\_macros} is just
543a list of macros to undefine.
544
545For example:
Fred Drakea09262e2001-03-01 18:35:43 +0000546
Greg Ward2afffd42000-08-06 20:37:24 +0000547\begin{verbatim}
548Extension(...,
549 define_macros=[('NDEBUG', '1')],
550 ('HAVE_STRFTIME', None),
551 undef_macros=['HAVE_FOO', 'HAVE_BAR'])
552\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000553
Greg Ward2afffd42000-08-06 20:37:24 +0000554is the equivalent of having this at the top of every C source file:
Fred Drakea09262e2001-03-01 18:35:43 +0000555
Greg Ward2afffd42000-08-06 20:37:24 +0000556\begin{verbatim}
557#define NDEBUG 1
558#define HAVE_STRFTIME
559#undef HAVE_FOO
560#undef HAVE_BAR
561\end{verbatim}
562
563
564\subsubsection{Library options}
565
566You can also specify the libraries to link against when building your
567extension, and the directories to search for those libraries. The
568\code{libraries} option is a list of libraries to link against,
569\code{library\_dirs} is a list of directories to search for libraries at
570link-time, and \code{runtime\_library\_dirs} is a list of directories to
571search for shared (dynamically loaded) libraries at run-time.
572
573For example, if you need to link against libraries known to be in the
574standard library search path on target systems
Fred Drakea09262e2001-03-01 18:35:43 +0000575
Greg Ward2afffd42000-08-06 20:37:24 +0000576\begin{verbatim}
577Extension(...,
578 libraries=["gdbm", "readline"])
579\end{verbatim}
580
581If you need to link with libraries in a non-standard location, you'll
582have to include the location in \code{library\_dirs}:
Fred Drakea09262e2001-03-01 18:35:43 +0000583
Greg Ward2afffd42000-08-06 20:37:24 +0000584\begin{verbatim}
585Extension(...,
586 library_dirs=["/usr/X11R6/lib"],
587 libraries=["X11", "Xt"])
588\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000589
Greg Ward2afffd42000-08-06 20:37:24 +0000590(Again, this sort of non-portable construct should be avoided if you
591intend to distribute your code.)
592
Thomas Heller5f52f722001-02-19 17:48:03 +0000593\XXX{Should mention clib libraries here or somewhere else!}
594
595\subsubsection{Other options}
596
597There are still some other options which can be used to handle special
598cases.
599
600The \option{extra\_objects} option is a list of object files to be passed
601to the linker. These files must not have extensions, as the default
602extension for the compiler is used.
603
604\option{extra\_compile\_args} and \option{extra\_link\_args} can be used
605to specify additional command line options for the compiler resp.
606the linker command line.
607
608\option{export\_symbols} is only useful on windows, it can contain a list
609of symbols (functions or variables) to be exported. This option
610is not needed when building compiled extensions: the \code{initmodule}
611function will automatically be added to the exported symbols list
612by Distutils.
613
614\subsection{Listing scripts}
615So far we have been dealing with pure and non-pure Python modules,
616which are usually not run by themselves but imported by scripts.
617
618Scripts are files containing Python source code, indended to be started
619from the command line.
620Distutils doesn't provide much functionality for the scripts: the only
621support Distutils gives is to adjust the first line of the script
Fred Drakef2502ad2001-02-19 19:14:50 +0000622if it starts with \code{\#!} and contains the word ``python'' to refer
Thomas Heller5f52f722001-02-19 17:48:03 +0000623to the current interpreter location.
624
625The \option{scripts} option simply is a list of files to be handled
626in this way.
627
628
629\subsection{Listing additional files}
Fred Drakea09262e2001-03-01 18:35:43 +0000630
Thomas Heller5f52f722001-02-19 17:48:03 +0000631The \option{data\_files} option can be used to specify additional
632files needed by the module distribution: configuration files,
633data files, anything which does not fit in the previous categories.
634
Fred Drake632bda32002-03-08 22:02:06 +0000635\option{data\_files} specifies a sequence of (\var{directory},
636\var{files}) pairs in the following way:
Fred Drakea09262e2001-03-01 18:35:43 +0000637
Thomas Heller5f52f722001-02-19 17:48:03 +0000638\begin{verbatim}
639setup(...
640 data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
641 ('config', ['cfg/data.cfg'])])
642\end{verbatim}
643
644Note that you can specify the directory names where the data files
645will be installed, but you cannot rename the data files themselves.
646
Fred Drake632bda32002-03-08 22:02:06 +0000647Each (\var{directory}, \var{files}) pair in the sequence specifies the
648installation directory and the files to install there. If
649\var{directory} is a relative path, it is interpreted relative to the
650installation prefix (Python's \code{sys.prefix} for pure-Python
651packages, \code{sys.exec_prefix} for packages that contain extension
652modules). Each file name in \var{files} is interpreted relative to
653the \file{setup.py} script at the top of the package source
654distribution. No directory information from \var{files} is used to
655determine the final location of the installed file; only the name of
656the file is used.
657
Thomas Heller5f52f722001-02-19 17:48:03 +0000658You can specify the \option{data\_files} options as a simple sequence
659of files without specifying a target directory, but this is not recommended,
660and the \command{install} command will print a warning in this case.
661To install data files directly in the target directory, an empty
662string should be given as the directory.
Greg Ward16aafcd2000-04-09 04:06:44 +0000663
664
665\section{Writing the Setup Configuration File}
Greg Warde78298a2000-04-28 17:12:24 +0000666\label{setup-config}
Greg Ward16aafcd2000-04-09 04:06:44 +0000667
Greg Ward16aafcd2000-04-09 04:06:44 +0000668Often, it's not possible to write down everything needed to build a
Greg Ward47f99a62000-09-04 20:07:15 +0000669distribution \emph{a priori}: you may need to get some information from
670the user, or from the user's system, in order to proceed. As long as
671that information is fairly simple---a list of directories to search for
672C header files or libraries, for example---then providing a
673configuration file, \file{setup.cfg}, for users to edit is a cheap and
674easy way to solicit it. Configuration files also let you provide
675default values for any command option, which the installer can then
676override either on the command-line or by editing the config file.
Greg Ward16aafcd2000-04-09 04:06:44 +0000677
Greg Ward47f99a62000-09-04 20:07:15 +0000678(If you have more advanced needs, such as determining which extensions
679to build based on what capabilities are present on the target system,
680then you need the Distutils ``auto-configuration'' facility. This
681started to appear in Distutils 0.9 but, as of this writing, isn't mature
682or stable enough yet for real-world use.)
Greg Ward16aafcd2000-04-09 04:06:44 +0000683
Greg Ward47f99a62000-09-04 20:07:15 +0000684The setup configuration file is a useful middle-ground between the setup
685script---which, ideally, would be opaque to installers\footnote{This
686 ideal probably won't be achieved until auto-configuration is fully
687 supported by the Distutils.}---and the command-line to the setup
688script, which is outside of your control and entirely up to the
689installer. In fact, \file{setup.cfg} (and any other Distutils
690configuration files present on the target system) are processed after
691the contents of the setup script, but before the command-line. This has
692several useful consequences:
693\begin{itemize}
694\item installers can override some of what you put in \file{setup.py} by
695 editing \file{setup.cfg}
696\item you can provide non-standard defaults for options that are not
697 easily set in \file{setup.py}
698\item installers can override anything in \file{setup.cfg} using the
699 command-line options to \file{setup.py}
700\end{itemize}
701
702The basic syntax of the configuration file is simple:
Fred Drakea09262e2001-03-01 18:35:43 +0000703
Greg Ward47f99a62000-09-04 20:07:15 +0000704\begin{verbatim}
705[command]
706option=value
707...
708\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000709
Greg Ward47f99a62000-09-04 20:07:15 +0000710where \var{command} is one of the Distutils commands (e.g.
711\command{build\_py}, \command{install}), and \var{option} is one of the
712options that command supports. Any number of options can be supplied
713for each command, and any number of command sections can be included in
Fred Drake78489a32000-11-22 16:06:16 +0000714the file. Blank lines are ignored, as are comments (from a
715\character{\#} character to end-of-line). Long option values can be
716split across multiple lines simply by indenting the continuation lines.
Greg Ward47f99a62000-09-04 20:07:15 +0000717
718You can find out the list of options supported by a particular command
719with the universal \longprogramopt{help} option, e.g.
Fred Drakea09262e2001-03-01 18:35:43 +0000720
Greg Ward47f99a62000-09-04 20:07:15 +0000721\begin{verbatim}
722> python setup.py --help build_ext
723[...]
724Options for 'build_ext' command:
725 --build-lib (-b) directory for compiled extension modules
726 --build-temp (-t) directory for temporary files (build by-products)
727 --inplace (-i) ignore build-lib and put compiled extensions into the
728 source directory alongside your pure Python modules
729 --include-dirs (-I) list of directories to search for header files
730 --define (-D) C preprocessor macros to define
731 --undef (-U) C preprocessor macros to undefine
732[...]
733\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000734
Greg Ward47f99a62000-09-04 20:07:15 +0000735Or consult section \ref{reference} of this document (the command
736reference).
737
738Note that an option spelled \longprogramopt{foo-bar} on the command-line
739is spelled \option{foo\_bar} in configuration files.
740
741For example, say you want your extensions to be built
742``in-place''---that is, you have an extension \module{pkg.ext}, and you
Fred Drakeeff9a872000-10-26 16:41:03 +0000743want the compiled extension file (\file{ext.so} on \UNIX, say) to be put
Greg Ward47f99a62000-09-04 20:07:15 +0000744in the same source directory as your pure Python modules
745\module{pkg.mod1} and \module{pkg.mod2}. You can always use the
746\longprogramopt{inplace} option on the command-line to ensure this:
Fred Drakea09262e2001-03-01 18:35:43 +0000747
Greg Ward47f99a62000-09-04 20:07:15 +0000748\begin{verbatim}
749python setup.py build_ext --inplace
750\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000751
Greg Ward47f99a62000-09-04 20:07:15 +0000752But this requires that you always specify the \command{build\_ext}
753command explicitly, and remember to provide \longprogramopt{inplace}.
754An easier way is to ``set and forget'' this option, by encoding it in
755\file{setup.cfg}, the configuration file for this distribution:
Fred Drakea09262e2001-03-01 18:35:43 +0000756
Greg Ward47f99a62000-09-04 20:07:15 +0000757\begin{verbatim}
758[build_ext]
759inplace=1
760\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000761
Greg Ward47f99a62000-09-04 20:07:15 +0000762This will affect all builds of this module distribution, whether or not
763you explcitly specify \command{build\_ext}. If you include
764\file{setup.cfg} in your source distribution, it will also affect
765end-user builds---which is probably a bad idea for this option, since
766always building extensions in-place would break installation of the
767module distribution. In certain peculiar cases, though, modules are
768built right in their installation directory, so this is conceivably a
769useful ability. (Distributing extensions that expect to be built in
770their installation directory is almost always a bad idea, though.)
771
772Another example: certain commands take a lot of options that don't
773change from run-to-run; for example, \command{bdist\_rpm} needs to know
774everything required to generate a ``spec'' file for creating an RPM
775distribution. Some of this information comes from the setup script, and
776some is automatically generated by the Distutils (such as the list of
777files installed). But some of it has to be supplied as options to
778\command{bdist\_rpm}, which would be very tedious to do on the
779command-line for every run. Hence, here is a snippet from the
780Distutils' own \file{setup.cfg}:
Fred Drakea09262e2001-03-01 18:35:43 +0000781
Greg Ward47f99a62000-09-04 20:07:15 +0000782\begin{verbatim}
783[bdist_rpm]
784release = 1
785packager = Greg Ward <gward@python.net>
786doc_files = CHANGES.txt
787 README.txt
788 USAGE.txt
789 doc/
790 examples/
791\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000792
Greg Ward47f99a62000-09-04 20:07:15 +0000793Note that the \option{doc\_files} option is simply a
794whitespace-separated string split across multiple lines for readability.
Greg Ward16aafcd2000-04-09 04:06:44 +0000795
796
Fred Drakea09262e2001-03-01 18:35:43 +0000797\begin{seealso}
798 \seetitle[../inst/config-syntax.html]{Installing Python
799 Modules}{More information on the configuration files is
800 available in the manual for system administrators.}
801\end{seealso}
802
803
Greg Ward16aafcd2000-04-09 04:06:44 +0000804\section{Creating a Source Distribution}
Greg Warde78298a2000-04-28 17:12:24 +0000805\label{source-dist}
Greg Ward16aafcd2000-04-09 04:06:44 +0000806
Greg Warde78298a2000-04-28 17:12:24 +0000807As shown in section~\ref{simple-example}, you use the
Greg Ward16aafcd2000-04-09 04:06:44 +0000808\command{sdist} command to create a source distribution. In the
809simplest case,
Fred Drakea09262e2001-03-01 18:35:43 +0000810
Greg Ward16aafcd2000-04-09 04:06:44 +0000811\begin{verbatim}
812python setup.py sdist
813\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000814
Greg Ward19c67f82000-06-24 01:33:16 +0000815(assuming you haven't specified any \command{sdist} options in the setup
816script or config file), \command{sdist} creates the archive of the
Greg Ward54589d42000-09-06 01:37:35 +0000817default format for the current platform. The default format is gzip'ed
Fred Drakeeff9a872000-10-26 16:41:03 +0000818tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
819\XXX{no MacOS support here}
Greg Ward54589d42000-09-06 01:37:35 +0000820
Greg Wardd5767a52000-04-19 22:48:09 +0000821You can specify as many formats as you like using the
822\longprogramopt{formats} option, for example:
Fred Drakea09262e2001-03-01 18:35:43 +0000823
Greg Ward16aafcd2000-04-09 04:06:44 +0000824\begin{verbatim}
825python setup.py sdist --formats=gztar,zip
826\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000827
Greg Ward16aafcd2000-04-09 04:06:44 +0000828to create a gzipped tarball and a zip file. The available formats are:
Greg Ward46b98e32000-04-14 01:53:36 +0000829\begin{tableiii}{l|l|c}{code}%
830 {Format}{Description}{Notes}
Greg Ward54589d42000-09-06 01:37:35 +0000831 \lineiii{zip}{zip file (\file{.zip})}{(1),(3)}
832 \lineiii{gztar}{gzip'ed tar file (\file{.tar.gz})}{(2),(4)}
Greg Ward47f99a62000-09-04 20:07:15 +0000833 \lineiii{bztar}{bzip2'ed tar file (\file{.tar.gz})}{(4)}
834 \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(4)}
Greg Ward54589d42000-09-06 01:37:35 +0000835 \lineiii{tar}{tar file (\file{.tar})}{(4)}
Greg Ward46b98e32000-04-14 01:53:36 +0000836\end{tableiii}
837
838\noindent Notes:
839\begin{description}
840\item[(1)] default on Windows
Fred Drakeeff9a872000-10-26 16:41:03 +0000841\item[(2)] default on \UNIX
Greg Wardb6528972000-09-07 02:40:37 +0000842\item[(3)] requires either external \program{zip} utility or
843 \module{zipfile} module (not part of the standard Python library)
Greg Ward47f99a62000-09-04 20:07:15 +0000844\item[(4)] requires external utilities: \program{tar} and possibly one
845 of \program{gzip}, \program{bzip2}, or \program{compress}
Greg Ward46b98e32000-04-14 01:53:36 +0000846\end{description}
Greg Ward16aafcd2000-04-09 04:06:44 +0000847
848
Greg Ward54589d42000-09-06 01:37:35 +0000849
850\subsection{Specifying the files to distribute}
Greg Warde78298a2000-04-28 17:12:24 +0000851\label{manifest}
Greg Ward16aafcd2000-04-09 04:06:44 +0000852
Greg Ward54589d42000-09-06 01:37:35 +0000853If you don't supply an explicit list of files (or instructions on how to
854generate one), the \command{sdist} command puts a minimal default set
855into the source distribution:
Greg Ward16aafcd2000-04-09 04:06:44 +0000856\begin{itemize}
Greg Wardfacb8db2000-04-09 04:32:40 +0000857\item all Python source files implied by the \option{py\_modules} and
Greg Ward16aafcd2000-04-09 04:06:44 +0000858 \option{packages} options
Greg Wardfacb8db2000-04-09 04:32:40 +0000859\item all C source files mentioned in the \option{ext\_modules} or
Greg Ward16aafcd2000-04-09 04:06:44 +0000860 \option{libraries} options (\XXX{getting C library sources currently
Greg Wardfacb8db2000-04-09 04:32:40 +0000861 broken -- no get\_source\_files() method in build\_clib.py!})
Greg Ward16aafcd2000-04-09 04:06:44 +0000862\item anything that looks like a test script: \file{test/test*.py}
863 (currently, the Distutils don't do anything with test scripts except
864 include them in source distributions, but in the future there will be
865 a standard for testing Python module distributions)
Greg Ward54589d42000-09-06 01:37:35 +0000866\item \file{README.txt} (or \file{README}), \file{setup.py} (or whatever
867 you called your setup script), and \file{setup.cfg}
Greg Ward16aafcd2000-04-09 04:06:44 +0000868\end{itemize}
869Sometimes this is enough, but usually you will want to specify
870additional files to distribute. The typical way to do this is to write
871a \emph{manifest template}, called \file{MANIFEST.in} by default. The
Greg Ward54589d42000-09-06 01:37:35 +0000872manifest template is just a list of instructions for how to generate
873your manifest file, \file{MANIFEST}, which is the exact list of files to
874include in your source distribution. The \command{sdist} command
875processes this template and generates a manifest based on its
876instructions and what it finds in the filesystem.
877
878If you prefer to roll your own manifest file, the format is simple: one
879filename per line, regular files (or symlinks to them) only. If you do
880supply your own \file{MANIFEST}, you must specify everything: the
881default set of files described above does not apply in this case.
Greg Ward16aafcd2000-04-09 04:06:44 +0000882
883The manifest template has one command per line, where each command
884specifies a set of files to include or exclude from the source
885distribution. For an example, again we turn to the Distutils' own
886manifest template:
Fred Drakea09262e2001-03-01 18:35:43 +0000887
Greg Ward16aafcd2000-04-09 04:06:44 +0000888\begin{verbatim}
889include *.txt
Greg Ward87da1ea2000-04-21 04:35:25 +0000890recursive-include examples *.txt *.py
Greg Ward16aafcd2000-04-09 04:06:44 +0000891prune examples/sample?/build
892\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000893
Greg Ward16aafcd2000-04-09 04:06:44 +0000894The meanings should be fairly clear: include all files in the
895distribution root matching \code{*.txt}, all files anywhere under the
896\file{examples} directory matching \code{*.txt} or \code{*.py}, and
Greg Ward54589d42000-09-06 01:37:35 +0000897exclude all directories matching \code{examples/sample?/build}. All of
898this is done \emph{after} the standard include set, so you can exclude
899files from the standard set with explicit instructions in the manifest
900template. (Or, you can use the \longprogramopt{no-defaults} option to
901disable the standard set entirely.) There are several other commands
902available in the manifest template mini-language; see
903section~\ref{sdist-cmd}.
Greg Ward16aafcd2000-04-09 04:06:44 +0000904
Greg Ward54589d42000-09-06 01:37:35 +0000905The order of commands in the manifest template matters: initially, we
906have the list of default files as described above, and each command in
907the template adds to or removes from that list of files. Once we have
908fully processed the manifest template, we remove files that should not
909be included in the source distribution:
910\begin{itemize}
911\item all files in the Distutils ``build'' tree (default \file{build/})
912\item all files in directories named \file{RCS} or \file{CVS}
913\end{itemize}
914Now we have our complete list of files, which is written to the manifest
915for future reference, and then used to build the source distribution
916archive(s).
917
918You can disable the default set of included files with the
919\longprogramopt{no-defaults} option, and you can disable the standard
920exclude set with \longprogramopt{no-prune}.
Greg Ward16aafcd2000-04-09 04:06:44 +0000921
Greg Ward46b98e32000-04-14 01:53:36 +0000922Following the Distutils' own manifest template, let's trace how the
Greg Ward47f99a62000-09-04 20:07:15 +0000923\command{sdist} command builds the list of files to include in the
Greg Ward46b98e32000-04-14 01:53:36 +0000924Distutils source distribution:
Greg Ward16aafcd2000-04-09 04:06:44 +0000925\begin{enumerate}
926\item include all Python source files in the \file{distutils} and
927 \file{distutils/command} subdirectories (because packages
928 corresponding to those two directories were mentioned in the
Greg Ward54589d42000-09-06 01:37:35 +0000929 \option{packages} option in the setup script---see
930 section~\ref{setup-script})
931\item include \file{README.txt}, \file{setup.py}, and \file{setup.cfg}
932 (standard files)
933\item include \file{test/test*.py} (standard files)
Greg Ward16aafcd2000-04-09 04:06:44 +0000934\item include \file{*.txt} in the distribution root (this will find
935 \file{README.txt} a second time, but such redundancies are weeded out
936 later)
Greg Ward54589d42000-09-06 01:37:35 +0000937\item include anything matching \file{*.txt} or \file{*.py} in the
938 sub-tree under \file{examples},
939\item exclude all files in the sub-trees starting at directories
940 matching \file{examples/sample?/build}---this may exclude files
941 included by the previous two steps, so it's important that the
942 \code{prune} command in the manifest template comes after the
943 \code{recursive-include} command
944\item exclude the entire \file{build} tree, and any \file{RCS} or
945 \file{CVS} directories
Greg Wardfacb8db2000-04-09 04:32:40 +0000946\end{enumerate}
Greg Ward46b98e32000-04-14 01:53:36 +0000947Just like in the setup script, file and directory names in the manifest
948template should always be slash-separated; the Distutils will take care
949of converting them to the standard representation on your platform.
950That way, the manifest template is portable across operating systems.
951
Greg Ward16aafcd2000-04-09 04:06:44 +0000952
953\subsection{Manifest-related options}
Greg Warde78298a2000-04-28 17:12:24 +0000954\label{manifest-options}
Greg Ward16aafcd2000-04-09 04:06:44 +0000955
956The normal course of operations for the \command{sdist} command is as
957follows:
958\begin{itemize}
Greg Ward46b98e32000-04-14 01:53:36 +0000959\item if the manifest file, \file{MANIFEST} doesn't exist, read
960 \file{MANIFEST.in} and create the manifest
Greg Ward54589d42000-09-06 01:37:35 +0000961\item if neither \file{MANIFEST} nor \file{MANIFEST.in} exist, create a
962 manifest with just the default file set\footnote{In versions of the
963 Distutils up to and including 0.9.2 (Python 2.0b1), this feature was
964 broken; use the \programopt{-f} (\longprogramopt{force-manifest})
965 option to work around the bug.}
Greg Ward1d8f57a2000-08-05 00:43:11 +0000966\item if either \file{MANIFEST.in} or the setup script (\file{setup.py})
967 are more recent than \file{MANIFEST}, recreate \file{MANIFEST} by
968 reading \file{MANIFEST.in}
Greg Ward16aafcd2000-04-09 04:06:44 +0000969\item use the list of files now in \file{MANIFEST} (either just
970 generated or read in) to create the source distribution archive(s)
971\end{itemize}
Greg Ward54589d42000-09-06 01:37:35 +0000972There are a couple of options that modify this behaviour. First, use
973the \longprogramopt{no-defaults} and \longprogramopt{no-prune} to
974disable the standard ``include'' and ``exclude'' sets.\footnote{Note
975 that if you have no manifest template, no manifest, and use the
976 \longprogramopt{no-defaults}, you will get an empty manifest. Another
977 bug in Distutils 0.9.2 and earlier causes an uncaught exception in
978 this case. The workaround is: Don't Do That.}
Greg Ward16aafcd2000-04-09 04:06:44 +0000979
Greg Ward54589d42000-09-06 01:37:35 +0000980Second, you might want to force the manifest to be regenerated---for
Greg Ward16aafcd2000-04-09 04:06:44 +0000981example, if you have added or removed files or directories that match an
982existing pattern in the manifest template, you should regenerate the
983manifest:
Fred Drakea09262e2001-03-01 18:35:43 +0000984
Greg Ward16aafcd2000-04-09 04:06:44 +0000985\begin{verbatim}
986python setup.py sdist --force-manifest
987\end{verbatim}
Greg Ward16aafcd2000-04-09 04:06:44 +0000988
989Or, you might just want to (re)generate the manifest, but not create a
990source distribution:
Fred Drakea09262e2001-03-01 18:35:43 +0000991
Greg Ward16aafcd2000-04-09 04:06:44 +0000992\begin{verbatim}
993python setup.py sdist --manifest-only
994\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +0000995
Greg Ward54589d42000-09-06 01:37:35 +0000996\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
997\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
998\programopt{-f} for \longprogramopt{force-manifest}.
Greg Ward16aafcd2000-04-09 04:06:44 +0000999
1000
1001\section{Creating Built Distributions}
Greg Warde78298a2000-04-28 17:12:24 +00001002\label{built-dist}
Greg Ward16aafcd2000-04-09 04:06:44 +00001003
Greg Ward46b98e32000-04-14 01:53:36 +00001004A ``built distribution'' is what you're probably used to thinking of
1005either as a ``binary package'' or an ``installer'' (depending on your
1006background). It's not necessarily binary, though, because it might
1007contain only Python source code and/or byte-code; and we don't call it a
1008package, because that word is already spoken for in Python. (And
1009``installer'' is a term specific to the Windows world. \XXX{do Mac
1010 people use it?})
Greg Ward16aafcd2000-04-09 04:06:44 +00001011
Greg Ward46b98e32000-04-14 01:53:36 +00001012A built distribution is how you make life as easy as possible for
1013installers of your module distribution: for users of RPM-based Linux
1014systems, it's a binary RPM; for Windows users, it's an executable
1015installer; for Debian-based Linux users, it's a Debian package; and so
1016forth. Obviously, no one person will be able to create built
Greg Wardb6528972000-09-07 02:40:37 +00001017distributions for every platform under the sun, so the Distutils are
Greg Ward46b98e32000-04-14 01:53:36 +00001018designed to enable module developers to concentrate on their
1019specialty---writing code and creating source distributions---while an
1020intermediary species of \emph{packager} springs up to turn source
Greg Ward19c67f82000-06-24 01:33:16 +00001021distributions into built distributions for as many platforms as there
Greg Ward46b98e32000-04-14 01:53:36 +00001022are packagers.
1023
1024Of course, the module developer could be his own packager; or the
1025packager could be a volunteer ``out there'' somewhere who has access to
1026a platform which the original developer does not; or it could be
1027software periodically grabbing new source distributions and turning them
1028into built distributions for as many platforms as the software has
1029access to. Regardless of the nature of the beast, a packager uses the
1030setup script and the \command{bdist} command family to generate built
1031distributions.
1032
1033As a simple example, if I run the following command in the Distutils
1034source tree:
Fred Drakea09262e2001-03-01 18:35:43 +00001035
Greg Ward46b98e32000-04-14 01:53:36 +00001036\begin{verbatim}
1037python setup.py bdist
1038\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001039
Greg Ward46b98e32000-04-14 01:53:36 +00001040then the Distutils builds my module distribution (the Distutils itself
1041in this case), does a ``fake'' installation (also in the \file{build}
1042directory), and creates the default type of built distribution for my
Greg Wardb6528972000-09-07 02:40:37 +00001043platform. The default format for built distributions is a ``dumb'' tar
Fred Drakeeff9a872000-10-26 16:41:03 +00001044file on \UNIX, and an simple executable installer on Windows. (That tar
Greg Wardb6528972000-09-07 02:40:37 +00001045file is considered ``dumb'' because it has to be unpacked in a specific
1046location to work.)
Greg Ward1d8f57a2000-08-05 00:43:11 +00001047
Fred Drakeeff9a872000-10-26 16:41:03 +00001048Thus, the above command on a \UNIX{} system creates
Greg Ward1d8f57a2000-08-05 00:43:11 +00001049\file{Distutils-0.9.1.\filevar{plat}.tar.gz}; unpacking this tarball
Greg Wardb6528972000-09-07 02:40:37 +00001050from the right place installs the Distutils just as though you had
1051downloaded the source distribution and run \code{python setup.py
1052 install}. (The ``right place'' is either the root of the filesystem or
1053Python's \filevar{prefix} directory, depending on the options given to
1054the \command{bdist\_dumb} command; the default is to make dumb
1055distributions relative to \filevar{prefix}.)
Greg Ward46b98e32000-04-14 01:53:36 +00001056
Greg Wardb6528972000-09-07 02:40:37 +00001057Obviously, for pure Python distributions, this isn't a huge win---but
1058for non-pure distributions, which include extensions that would need to
1059be compiled, it can mean the difference between someone being able to
1060use your extensions or not. And creating ``smart'' built distributions,
1061such as an RPM package or an executable installer for Windows, is a big
1062win for users even if your distribution doesn't include any extensions.
Greg Ward46b98e32000-04-14 01:53:36 +00001063
Greg Wardb6528972000-09-07 02:40:37 +00001064The \command{bdist} command has a \longprogramopt{formats} option,
Greg Ward1d8f57a2000-08-05 00:43:11 +00001065similar to the \command{sdist} command, which you can use to select the
1066types of built distribution to generate: for example,
Fred Drakea09262e2001-03-01 18:35:43 +00001067
Greg Ward46b98e32000-04-14 01:53:36 +00001068\begin{verbatim}
1069python setup.py bdist --format=zip
1070\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001071
Fred Drakeeff9a872000-10-26 16:41:03 +00001072would, when run on a \UNIX{} system, create
Greg Ward1d8f57a2000-08-05 00:43:11 +00001073\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
1074unpacked from the root directory to install the Distutils.
Greg Ward46b98e32000-04-14 01:53:36 +00001075
1076The available formats for built distributions are:
1077\begin{tableiii}{l|l|c}{code}%
1078 {Format}{Description}{Notes}
Greg Wardb6528972000-09-07 02:40:37 +00001079 \lineiii{gztar}{gzipped tar file (\file{.tar.gz})}{(1),(3)}
1080 \lineiii{ztar}{compressed tar file (\file{.tar.Z})}{(3)}
1081 \lineiii{tar}{tar file (\file{.tar})}{(3)}
1082 \lineiii{zip}{zip file (\file{.zip})}{(4)}
1083 \lineiii{rpm}{RPM}{(5)}
1084 \lineiii{srpm}{source RPM}{(5) \XXX{to do!}}
Thomas Heller5f52f722001-02-19 17:48:03 +00001085 \lineiii{wininst}{self-extracting ZIP file for Windows}{(2),(4)}
Greg Ward46b98e32000-04-14 01:53:36 +00001086\end{tableiii}
1087
1088\noindent Notes:
1089\begin{description}
Fred Drakeeff9a872000-10-26 16:41:03 +00001090\item[(1)] default on \UNIX
Greg Ward1d8f57a2000-08-05 00:43:11 +00001091\item[(2)] default on Windows \XXX{to-do!}
Greg Wardb6528972000-09-07 02:40:37 +00001092\item[(3)] requires external utilities: \program{tar} and possibly one
1093 of \program{gzip}, \program{bzip2}, or \program{compress}
1094\item[(4)] requires either external \program{zip} utility or
1095 \module{zipfile} module (not part of the standard Python library)
1096\item[(5)] requires external \program{rpm} utility, version 3.0.4 or
1097 better (use \code{rpm --version} to find out which version you have)
Greg Ward46b98e32000-04-14 01:53:36 +00001098\end{description}
1099
1100You don't have to use the \command{bdist} command with the
Greg Wardd5767a52000-04-19 22:48:09 +00001101\longprogramopt{formats} option; you can also use the command that
Greg Ward1d8f57a2000-08-05 00:43:11 +00001102directly implements the format you're interested in. Some of these
Greg Ward46b98e32000-04-14 01:53:36 +00001103\command{bdist} ``sub-commands'' actually generate several similar
1104formats; for instance, the \command{bdist\_dumb} command generates all
1105the ``dumb'' archive formats (\code{tar}, \code{ztar}, \code{gztar}, and
1106\code{zip}), and \command{bdist\_rpm} generates both binary and source
1107RPMs. The \command{bdist} sub-commands, and the formats generated by
1108each, are:
1109\begin{tableii}{l|l}{command}%
1110 {Command}{Formats}
1111 \lineii{bdist\_dumb}{tar, ztar, gztar, zip}
1112 \lineii{bdist\_rpm}{rpm, srpm}
Greg Ward1d8f57a2000-08-05 00:43:11 +00001113 \lineii{bdist\_wininst}{wininst}
Greg Ward46b98e32000-04-14 01:53:36 +00001114\end{tableii}
Greg Ward16aafcd2000-04-09 04:06:44 +00001115
Greg Wardb6528972000-09-07 02:40:37 +00001116The following sections give details on the individual \command{bdist\_*}
1117commands.
1118
1119
1120\subsection{Creating dumb built distributions}
1121\label{creating-dumb}
1122
1123\XXX{Need to document absolute vs. prefix-relative packages here, but
1124 first I have to implement it!}
1125
1126
1127\subsection{Creating RPM packages}
1128\label{creating-rpms}
1129
1130The RPM format is used by many of popular Linux distributions, including
1131Red Hat, SuSE, and Mandrake. If one of these (or any of the other
1132RPM-based Linux distributions) is your usual environment, creating RPM
1133packages for other users of that same distribution is trivial.
1134Depending on the complexity of your module distribution and differences
1135between Linux distributions, you may also be able to create RPMs that
1136work on different RPM-based distributions.
1137
1138The usual way to create an RPM of your module distribution is to run the
1139\command{bdist\_rpm} command:
Fred Drakea09262e2001-03-01 18:35:43 +00001140
Greg Wardb6528972000-09-07 02:40:37 +00001141\begin{verbatim}
1142python setup.py bdist_rpm
1143\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001144
Greg Wardb6528972000-09-07 02:40:37 +00001145or the \command{bdist} command with the \longprogramopt{format} option:
Fred Drakea09262e2001-03-01 18:35:43 +00001146
Greg Wardb6528972000-09-07 02:40:37 +00001147\begin{verbatim}
1148python setup.py bdist --formats=rpm
1149\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001150
Greg Wardb6528972000-09-07 02:40:37 +00001151The former allows you to specify RPM-specific options; the latter allows
1152you to easily specify multiple formats in one run. If you need to do
1153both, you can explicitly specify multiple \command{bdist\_*} commands
1154and their options:
Fred Drakea09262e2001-03-01 18:35:43 +00001155
Greg Wardb6528972000-09-07 02:40:37 +00001156\begin{verbatim}
1157python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
1158 bdist_wininst --target_version="2.0"
1159\end{verbatim}
1160
1161Creating RPM packages is driven by a \file{.spec} file, much as using
1162the Distutils is driven by the setup script. To make your life easier,
1163the \command{bdist\_rpm} command normally creates a \file{.spec} file
1164based on the information you supply in the setup script, on the command
1165line, and in any Distutils configuration files. Various options and
Andrew M. Kuchlingda23c4f2001-02-17 00:38:48 +00001166sections in the \file{.spec} file are derived from options in the setup
Greg Wardb6528972000-09-07 02:40:37 +00001167script as follows:
1168\begin{tableii}{l|l}{textrm}%
1169 {RPM \file{.spec} file option or section}{Distutils setup script option}
1170 \lineii{Name}{\option{name}}
1171 \lineii{Summary (in preamble)}{\option{description}}
1172 \lineii{Version}{\option{version}}
1173 \lineii{Vendor}{\option{author} and \option{author\_email}, or \\&
1174 \option{maintainer} and \option{maintainer\_email}}
1175 \lineii{Copyright}{\option{licence}}
1176 \lineii{Url}{\option{url}}
1177 \lineii{\%description (section)}{\option{long\_description}}
1178\end{tableii}
1179
1180Additionally, there many options in \file{.spec} files that don't have
1181corresponding options in the setup script. Most of these are handled
1182through options to the \command{bdist\_rpm} command as follows:
1183\begin{tableiii}{l|l|l}{textrm}%
1184 {RPM \file{.spec} file option or section}%
1185 {\command{bdist\_rpm} option}%
1186 {default value}
1187 \lineiii{Release}{\option{release}}{``1''}
1188 \lineiii{Group}{\option{group}}{``Development/Libraries''}
1189 \lineiii{Vendor}{\option{vendor}}{(see above)}
Andrew M. Kuchlingda23c4f2001-02-17 00:38:48 +00001190 \lineiii{Packager}{\option{packager}}{(none)}
1191 \lineiii{Provides}{\option{provides}}{(none)}
1192 \lineiii{Requires}{\option{requires}}{(none)}
1193 \lineiii{Conflicts}{\option{conflicts}}{(none)}
1194 \lineiii{Obsoletes}{\option{obsoletes}}{(none)}
Greg Wardb6528972000-09-07 02:40:37 +00001195 \lineiii{Distribution}{\option{distribution\_name}}{(none)}
1196 \lineiii{BuildRequires}{\option{build\_requires}}{(none)}
1197 \lineiii{Icon}{\option{icon}}{(none)}
1198\end{tableiii}
1199Obviously, supplying even a few of these options on the command-line
1200would be tedious and error-prone, so it's usually best to put them in
1201the setup configuration file, \file{setup.cfg}---see
1202section~\ref{setup-config}. If you distribute or package many Python
1203module distributions, you might want to put options that apply to all of
1204them in your personal Distutils configuration file
1205(\file{\textasciitilde/.pydistutils.cfg}).
1206
1207There are three steps to building a binary RPM package, all of which are
1208handled automatically by the Distutils:
1209\begin{enumerate}
1210\item create a \file{.spec} file, which describes the package (analogous
1211 to the Distutils setup script; in fact, much of the information in the
1212 setup script winds up in the \file{.spec} file)
1213\item create the source RPM
1214\item create the ``binary'' RPM (which may or may not contain binary
1215 code, depending on whether your module distribution contains Python
1216 extensions)
1217\end{enumerate}
1218Normally, RPM bundles the last two steps together; when you use the
1219Distutils, all three steps are typically bundled together.
1220
1221If you wish, you can separate these three steps. You can use the
1222\longprogramopt{spec-only} option to make \command{bdist\_rpm} just
1223create the \file{.spec} file and exit; in this case, the \file{.spec}
1224file will be written to the ``distribution directory''---normally
1225\file{dist/}, but customizable with the \longprogramopt{dist-dir}
1226option. (Normally, the \file{.spec} file winds up deep in the ``build
1227tree,'' in a temporary directory created by \command{bdist\_rpm}.)
1228
1229\XXX{this isn't implemented yet---is it needed?!}
1230You can also specify a custom \file{.spec} file with the
Thomas Heller5f52f722001-02-19 17:48:03 +00001231\longprogramopt{spec-file} option; used in conjunction with
Greg Wardb6528972000-09-07 02:40:37 +00001232\longprogramopt{spec-only}, this gives you an opportunity to customize
1233the \file{.spec} file manually:
Fred Drakea09262e2001-03-01 18:35:43 +00001234
Greg Wardb6528972000-09-07 02:40:37 +00001235\begin{verbatim}
1236> python setup.py bdist_rpm --spec-only
1237# ...edit dist/FooBar-1.0.spec
1238> python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
1239\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001240
Greg Wardb6528972000-09-07 02:40:37 +00001241(Although a better way to do this is probably to override the standard
1242\command{bdist\_rpm} command with one that writes whatever else you want
1243to the \file{.spec} file; see section~\ref{extending} for information on
1244extending the Distutils.)
1245
1246
1247\subsection{Creating Windows installers}
1248\label{creating-wininst}
1249
Thomas Heller5f52f722001-02-19 17:48:03 +00001250Executable Windows installers are the natural format for binary
Fred Drake17f690f2001-07-14 02:14:42 +00001251distributions on Windows. They display a nice graphical user interface,
1252display some information of the module distribution to be installed, taken
Fred Drake457c4192001-08-16 21:25:24 +00001253from the meta-data in the setup script, let the user select a few
Thomas Heller5f52f722001-02-19 17:48:03 +00001254(currently maybe too few) options, and start or cancel the installation.
Greg Wardb6528972000-09-07 02:40:37 +00001255
Thomas Heller5f52f722001-02-19 17:48:03 +00001256Since the meta-data is taken from the setup script, creating
1257Windows installers is usually as easy as running:
Fred Drakea09262e2001-03-01 18:35:43 +00001258
Thomas Heller5f52f722001-02-19 17:48:03 +00001259\begin{verbatim}
1260python setup.py bdist_wininst
1261\end{verbatim}
Fred Drakea09262e2001-03-01 18:35:43 +00001262
Thomas Heller5f52f722001-02-19 17:48:03 +00001263or the \command{bdist} command with the \longprogramopt{format} option:
Fred Drakea09262e2001-03-01 18:35:43 +00001264
Thomas Heller5f52f722001-02-19 17:48:03 +00001265\begin{verbatim}
1266python setup.py bdist --formats=wininst
1267\end{verbatim}
1268
1269If you have a pure module distribution (only containing pure
1270Python modules and packages), the resulting installer will be
1271version independent and have a name like \file{Foo-1.0.win32.exe}.
1272These installers can even be created on \UNIX{} or MacOS platforms.
1273
1274If you have a non-pure distribution, the extensions can only be
1275created on a Windows platform, and will be Python version dependend.
1276The installer filename will reflect this and now has the form
1277\file{Foo-1.0.win32-py2.0.exe}. You have to create a separate installer
1278for every Python version you want to support.
1279
1280The installer will try to compile pure modules into bytecode after
1281installation on the target system in normal and optimizing mode.
1282If you don't want this to happen for some reason, you can run
1283the bdist_wininst command with the \longprogramopt{no-target-compile} and/or
1284the \longprogramopt{no-target-optimize} option.
Greg Wardb6528972000-09-07 02:40:37 +00001285
Fred Drakea09262e2001-03-01 18:35:43 +00001286%\section{Examples}
1287%\label{examples}
Greg Ward16aafcd2000-04-09 04:06:44 +00001288
1289
Fred Drakea09262e2001-03-01 18:35:43 +00001290%\subsection{Pure Python distribution (by module)}
1291%\label{pure-mod}
Greg Ward16aafcd2000-04-09 04:06:44 +00001292
1293
Fred Drakea09262e2001-03-01 18:35:43 +00001294%\subsection{Pure Python distribution (by package)}
1295%\label{pure-pkg}
Greg Ward16aafcd2000-04-09 04:06:44 +00001296
1297
Fred Drakea09262e2001-03-01 18:35:43 +00001298%\subsection{Single extension module}
1299%\label{single-ext}
Greg Ward16aafcd2000-04-09 04:06:44 +00001300
1301
Fred Drakea09262e2001-03-01 18:35:43 +00001302%\subsection{Multiple extension modules}
1303%\label{multiple-ext}
Greg Ward16aafcd2000-04-09 04:06:44 +00001304
1305
Fred Drakea09262e2001-03-01 18:35:43 +00001306%\subsection{Putting it all together}
Greg Ward16aafcd2000-04-09 04:06:44 +00001307
1308
Greg Ward4a9e7222000-04-25 02:57:36 +00001309
Fred Drakea09262e2001-03-01 18:35:43 +00001310%\section{Extending the Distutils}
1311%\label{extending}
Greg Ward4a9e7222000-04-25 02:57:36 +00001312
1313
Fred Drakea09262e2001-03-01 18:35:43 +00001314%\subsection{Extending existing commands}
1315%\label{extend-existing}
Greg Ward4a9e7222000-04-25 02:57:36 +00001316
1317
Fred Drakea09262e2001-03-01 18:35:43 +00001318%\subsection{Writing new commands}
1319%\label{new-commands}
Greg Ward4a9e7222000-04-25 02:57:36 +00001320
Fred Drakea09262e2001-03-01 18:35:43 +00001321%\XXX{Would an uninstall command be a good example here?}
Thomas Heller5f52f722001-02-19 17:48:03 +00001322
Greg Ward4a9e7222000-04-25 02:57:36 +00001323
1324
Greg Ward16aafcd2000-04-09 04:06:44 +00001325\section{Reference}
Greg Ward47f99a62000-09-04 20:07:15 +00001326\label{reference}
Greg Ward16aafcd2000-04-09 04:06:44 +00001327
1328
Fred Drakea09262e2001-03-01 18:35:43 +00001329%\subsection{Building modules: the \protect\command{build} command family}
1330%\label{build-cmds}
Greg Ward16aafcd2000-04-09 04:06:44 +00001331
Fred Drakea09262e2001-03-01 18:35:43 +00001332%\subsubsection{\protect\command{build}}
1333%\label{build-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001334
Fred Drakea09262e2001-03-01 18:35:43 +00001335%\subsubsection{\protect\command{build\_py}}
1336%\label{build-py-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001337
Fred Drakea09262e2001-03-01 18:35:43 +00001338%\subsubsection{\protect\command{build\_ext}}
1339%\label{build-ext-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001340
Fred Drakea09262e2001-03-01 18:35:43 +00001341%\subsubsection{\protect\command{build\_clib}}
1342%\label{build-clib-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001343
1344
Greg Wardfacb8db2000-04-09 04:32:40 +00001345\subsection{Installing modules: the \protect\command{install} command family}
Greg Warde78298a2000-04-28 17:12:24 +00001346\label{install-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001347
Gregory P. Smith147e5f32000-05-12 00:58:18 +00001348The install command ensures that the build commands have been run and then
1349runs the subcommands \command{install\_lib},
1350\command{install\_data} and
1351\command{install\_scripts}.
1352
Fred Drakea09262e2001-03-01 18:35:43 +00001353%\subsubsection{\protect\command{install\_lib}}
1354%\label{install-lib-cmd}
Gregory P. Smith147e5f32000-05-12 00:58:18 +00001355
1356\subsubsection{\protect\command{install\_data}}
Greg Ward1365a302000-08-31 14:47:05 +00001357\label{install-data-cmd}
Gregory P. Smith147e5f32000-05-12 00:58:18 +00001358This command installs all data files provided with the distribution.
1359
1360\subsubsection{\protect\command{install\_scripts}}
Greg Ward1365a302000-08-31 14:47:05 +00001361\label{install-scripts-cmd}
Gregory P. Smith147e5f32000-05-12 00:58:18 +00001362This command installs all (Python) scripts in the distribution.
1363
Greg Ward16aafcd2000-04-09 04:06:44 +00001364
Fred Drakea09262e2001-03-01 18:35:43 +00001365%\subsection{Cleaning up: the \protect\command{clean} command}
1366%\label{clean-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001367
1368
Fred Drakeeff9a872000-10-26 16:41:03 +00001369\subsection{Creating a source distribution: the
1370 \protect\command{sdist} command}
Greg Warde78298a2000-04-28 17:12:24 +00001371\label{sdist-cmd}
Greg Ward16aafcd2000-04-09 04:06:44 +00001372
1373
1374\XXX{fragment moved down from above: needs context!}
Greg Wardb6528972000-09-07 02:40:37 +00001375
Greg Ward16aafcd2000-04-09 04:06:44 +00001376The manifest template commands are:
1377\begin{tableii}{ll}{command}{Command}{Description}
Greg Ward87da1ea2000-04-21 04:35:25 +00001378 \lineii{include \var{pat1} \var{pat2} ... }
1379 {include all files matching any of the listed patterns}
1380 \lineii{exclude \var{pat1} \var{pat2} ... }
1381 {exclude all files matching any of the listed patterns}
1382 \lineii{recursive-include \var{dir} \var{pat1} \var{pat2} ... }
1383 {include all files under \var{dir} matching any of the listed patterns}
1384 \lineii{recursive-exclude \var{dir} \var{pat1} \var{pat2} ...}
1385 {exclude all files under \var{dir} matching any of the listed patterns}
1386 \lineii{global-include \var{pat1} \var{pat2} ...}
Greg Ward1bbe3292000-06-25 03:14:13 +00001387 {include all files anywhere in the source tree matching\\&
Greg Ward87da1ea2000-04-21 04:35:25 +00001388 any of the listed patterns}
1389 \lineii{global-exclude \var{pat1} \var{pat2} ...}
Greg Ward1bbe3292000-06-25 03:14:13 +00001390 {exclude all files anywhere in the source tree matching\\&
Greg Ward87da1ea2000-04-21 04:35:25 +00001391 any of the listed patterns}
Greg Ward16aafcd2000-04-09 04:06:44 +00001392 \lineii{prune \var{dir}}{exclude all files under \var{dir}}
1393 \lineii{graft \var{dir}}{include all files under \var{dir}}
1394\end{tableii}
Fred Drakeeff9a872000-10-26 16:41:03 +00001395The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any
Greg Ward16aafcd2000-04-09 04:06:44 +00001396sequence of regular filename characters, \code{?} matches any single
1397regular filename character, and \code{[\var{range}]} matches any of the
1398characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},
Greg Wardfacb8db2000-04-09 04:32:40 +00001399\code{a-f0-9\_.}). The definition of ``regular filename character'' is
Fred Drakeeff9a872000-10-26 16:41:03 +00001400platform-specific: on \UNIX{} it is anything except slash; on Windows
1401anything except backslash or colon; on MacOS anything except colon.
Greg Wardb6528972000-09-07 02:40:37 +00001402
Fred Drakeeff9a872000-10-26 16:41:03 +00001403\XXX{Windows and MacOS support not there yet}
Greg Ward16aafcd2000-04-09 04:06:44 +00001404
1405
Fred Drakea09262e2001-03-01 18:35:43 +00001406%\subsection{Creating a built distribution: the
1407% \protect\command{bdist} command family}
1408%\label{bdist-cmds}
Greg Ward16aafcd2000-04-09 04:06:44 +00001409
1410
Fred Drakeab70b382001-08-02 15:13:15 +00001411%\subsubsection{\protect\command{bdist}}
Greg Ward16aafcd2000-04-09 04:06:44 +00001412
Fred Drakeab70b382001-08-02 15:13:15 +00001413%\subsubsection{\protect\command{bdist\_dumb}}
Greg Ward16aafcd2000-04-09 04:06:44 +00001414
Fred Drakeab70b382001-08-02 15:13:15 +00001415%\subsubsection{\protect\command{bdist\_rpm}}
Greg Ward16aafcd2000-04-09 04:06:44 +00001416
Fred Drakeab70b382001-08-02 15:13:15 +00001417%\subsubsection{\protect\command{bdist\_wininst}}
1418
1419
1420\input{sysconfig}
Greg Ward16aafcd2000-04-09 04:06:44 +00001421
1422
Greg Wardabc52162000-02-26 00:52:48 +00001423\end{document}