traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

A grab-bag of wording tweakage.

This commit is contained in:
Greg Ward 2000-05-26 01:04:47 +00:00
parent 0e48cfd2c5
commit 59d382e482
1 changed files with 54 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
Doc/dist/dist.tex vendored
View File

@ -100,7 +100,7 @@ Windows) containing your setup script, \file{setup.py}, and your module,
\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,
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
@ -122,21 +122,29 @@ 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\_wise} command. (Wise is the installation tool used to
create Windows installers for Python itself, so we have adopted it for
use by any Python module distribution. 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}. For example:
\command{bdist\_wininst} command. For example:
\begin{verbatim}
python setup.py bdist_wise
python setup.py bdist_wininst
\end{verbatim}
will create an executable installer, \file{Foo-1\_0.exe}, in the current
directory.
\XXX{not implemented yet}
Other \command{bdist\_*} commands exist for RPM-based Linux systems
(\command{bdist\_rpm}), Debian-based Linux systems
(\command{bdist\_deb}), ...
(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}
@ -163,6 +171,12 @@ following glossary of common Python terms:
\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 ``package'' that modules not in a package live
in. 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. (The root package isn't really a package,
since it doesn't have an \file{\_\_init\_\_.py} file. But we have to
call it something.)
\end{description}
@ -177,8 +191,8 @@ distributing Python modules using the Distutils:
\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 spoken for in the Python context: a single module
distribution may contain zero, one, or many Python packages.)
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.''
@ -198,16 +212,17 @@ 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 suppled as keyword
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.)
other module distributions. The Distutils' own setup script is used to
install the package into Python 1.5.)
\begin{verbatim}
#!/usr/bin/env python
@ -235,13 +250,13 @@ 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 to whatever is appropriate on your
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 users should keep in mind that
the \emph{absence} of a leading slash indicates a relative directory,
the opposite of the Mac OS convention with colons).
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}
@ -283,12 +298,16 @@ would be written in the setup script as
\begin{verbatim}
package_dir = {'foo': 'lib'}
\end{verbatim}
Note that a \code{\var{package}: \var{dir}} entry in the
\option{package\_dir} option 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}.
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}
@ -307,8 +326,14 @@ 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. \XXX{not sure if this is actually
true---must check!}
\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}