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}. \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 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 and---from the \file{Foo-1.0} directory---run
\begin{verbatim} \begin{verbatim}
python setup.py install 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 running on a Windows machine, and want to make things easy for other
Windows users, you can create an executable installer (the most Windows users, you can create an executable installer (the most
appropriate type of built distribution for this platform) with the appropriate type of built distribution for this platform) with the
\command{bdist\_wise} command. (Wise is the installation tool used to \command{bdist\_wininst} command. For example:
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:
\begin{verbatim} \begin{verbatim}
python setup.py bdist_wise python setup.py bdist_wininst
\end{verbatim} \end{verbatim}
will create an executable installer, \file{Foo-1\_0.exe}, in the current will create an executable installer, \file{Foo-1\_0.exe}, in the current
directory. directory.
\XXX{not implemented yet} (Another way to create executable installers for Windows is with the
Other \command{bdist\_*} commands exist for RPM-based Linux systems \command{bdist\_wise} command, which uses Wise---the commercial
(\command{bdist\_rpm}), Debian-based Linux systems installer-generator used to create Python's own installer---to create
(\command{bdist\_deb}), ... 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} \subsection{General Python terminology}
@ -163,6 +171,12 @@ following glossary of common Python terms:
\item[package] a module that contains other modules; typically contained \item[package] a module that contains other modules; typically contained
in a directory in the filesystem and distinguished from other in a directory in the filesystem and distinguished from other
directories by the presence of a file \file{\_\_init\_\_.py}. 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} \end{description}
@ -177,8 +191,8 @@ distributing Python modules using the Distutils:
\emph{en masse}. Examples of some well-known module distributions are \emph{en masse}. Examples of some well-known module distributions are
Numeric Python, PyXML, PIL (the Python Imaging Library), or Numeric Python, PyXML, PIL (the Python Imaging Library), or
mxDateTime. (This would be called a \emph{package}, except that term mxDateTime. (This would be called a \emph{package}, except that term
is already spoken for in the Python context: a single module is already taken in the Python context: a single module distribution
distribution may contain zero, one, or many Python packages.) may contain zero, one, or many Python packages.)
\item[pure module distribution] a module distribution that contains only \item[pure module distribution] a module distribution that contains only
pure Python modules and packages. Sometimes referred to as a ``pure pure Python modules and packages. Sometimes referred to as a ``pure
distribution.'' 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 distributing, and installing modules using the Distutils. The main
purpose of the setup script is to describe your module distribution to purpose of the setup script is to describe your module distribution to
the Distutils, so that the various commands that operate on your modules the Distutils, so that the various commands that operate on your modules
do the right thing. As we saw in section~\ref{simple-example} do the right thing. As we saw in section~\ref{simple-example} above,
above, the setup script consists mainly of a call to \function{setup()}, the setup script consists mainly of a call to \function{setup()}, and
and all information supplied to the Distutils is suppled as keyword all information supplied to the Distutils is supplied as keyword
arguments to \function{setup()}. arguments to \function{setup()}.
Here's a slightly more involved example, which we'll follow for the next 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 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 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 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} \begin{verbatim}
#!/usr/bin/env python #!/usr/bin/env python
@ -235,13 +250,13 @@ maintain.
Note that any pathnames (files or directories) supplied in the setup Note that any pathnames (files or directories) supplied in the setup
script should be written using the Unix convention, i.e. script should be written using the Unix convention, i.e.
slash-separated. The Distutils will take care of converting this 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 current platform before actually using the pathname. This makes your
setup script portable across operating systems, which of course is one setup script portable across operating systems, which of course is one
of the major goals of the Distutils. In this spirit, all pathnames in 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 this document are slash-separated (Mac OS programmers should keep in
the \emph{absence} of a leading slash indicates a relative directory, mind that the \emph{absence} of a leading slash indicates a relative
the opposite of the Mac OS convention with colons). path, the opposite of the Mac OS convention with colons).
\subsection{Package directories} \subsection{Package directories}
@ -283,12 +298,16 @@ would be written in the setup script as
\begin{verbatim} \begin{verbatim}
package_dir = {'foo': 'lib'} package_dir = {'foo': 'lib'}
\end{verbatim} \end{verbatim}
Note that a \code{\var{package}: \var{dir}} entry in the A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
\option{package\_dir} option implicitly applies to all packages below dictionary implicitly applies to all packages below \var{package}, so
\var{package}, so the \module{foo.bar} case is automatically handled the \module{foo.bar} case is automatically handled here. In this
here. In this example, having \code{packages = ['foo', 'foo.bar']} example, having \code{packages = ['foo', 'foo.bar']} tells the Distutils
tells the Distutils to look for \file{lib/\_\_init\_\_.py} and to look for \file{lib/\_\_init\_\_.py} and
\file{lib/bar/\_\_init\_\_.py}. \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} \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 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. \file{pkg/mod2.py}, and that \file{pkg/\_\_init\_\_.py} exists as well.
And again, you can override the package/directory layout using the And again, you can override the package/directory layout using the
\option{package\_dir} option. \XXX{not sure if this is actually \option{package\_dir} option.
true---must check!}
\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} \section{Writing the Setup Configuration File}