[Python-checkins] python/dist/src/Doc/dist dist.tex,1.41,1.42
akuchling@users.sourceforge.net
akuchling@users.sourceforge.net
Wed, 29 May 2002 10:33:50 -0700
Update of /cvsroot/python/python/dist/src/Doc/dist
In directory usw-pr-cvs1:/tmp/cvs-serv5768
Modified Files:
dist.tex
Log Message:
Various minor rewrites
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.41
retrieving revision 1.42
diff -C2 -d -r1.41 -r1.42
*** dist.tex 10 May 2002 14:45:59 -0000 1.41
--- dist.tex 29 May 2002 17:33:48 -0000 1.42
***************
*** 22,26 ****
\noindent
This document describes the Python Distribution Utilities
! (``Distutils'') from the module developer's point-of-view, describing
how to use the Distutils to make Python modules and extensions easily
available to a wider audience with very little overhead for
--- 22,26 ----
\noindent
This document describes the Python Distribution Utilities
! (``Distutils'') from the module developer's point of view, describing
how to use the Distutils to make Python modules and extensions easily
available to a wider audience with very little overhead for
***************
*** 72,90 ****
! \subsection{A simple example}
\label{simple-example}
! The setup script is usually quite simple, although since it's written in
! Python, there are no arbitrary limits to what you can do with
! it, though you should be careful about putting arbitrarily expensive
! operations in your setup script. Unlike, say, Autoconf-style configure
! scripts, the setup script may be run multiple times in the course of
! building and installing your module distribution. If you need to
! insert potentially expensive processing steps into the Distutils
! chain, see section~\ref{extending} on extending the Distutils.
If all you want to do is distribute a module called \module{foo},
contained in a file \file{foo.py}, then your setup script can be as
! little as this:
\begin{verbatim}
--- 72,90 ----
! \subsection{A Simple Example}
\label{simple-example}
! The setup script is usually quite simple, although since it's written
! in Python, there are no arbitrary limits to what you can do with it,
! though you should be careful about putting arbitrarily expensive
! operations in your setup script. Unlike, say, Autoconf-style configure
! scripts, the setup script may be run multiple times in the course of
! building and installing your module distribution. If you need to
! insert potentially expensive processing steps into the Distutils
! chain, see section~\ref{extending} on extending the Distutils.
If all you want to do is distribute a module called \module{foo},
contained in a file \file{foo.py}, then your setup script can be as
! simple as this:
\begin{verbatim}
***************
*** 100,108 ****
keyword arguments to the \function{setup()} function
\item those keyword arguments fall into two categories: package
! meta-data (name, version number) and information about what's in the
package (a list of pure Python modules, in this case)
\item modules are specified by module name, not filename (the same will
hold true for packages and extensions)
! \item it's recommended that you supply a little more meta-data, in
particular your name, email address and a URL for the project
(see section~\ref{setup-script} for an example)
--- 100,108 ----
keyword arguments to the \function{setup()} function
\item those keyword arguments fall into two categories: package
! metadata (name, version number) and information about what's in the
package (a list of pure Python modules, in this case)
\item modules are specified by module name, not filename (the same will
hold true for packages and extensions)
! \item it's recommended that you supply a little more metadata, in
particular your name, email address and a URL for the project
(see section~\ref{setup-script} for an example)
***************
*** 117,121 ****
which will create an archive file (e.g., tarball on \UNIX, ZIP file on
! Windows) containing your setup script, \file{setup.py}, and your module,
\file{foo.py}. The archive file will be named \file{foo-1.0.tar.gz} (or
\file{.zip}), and will unpack into a directory \file{foo-1.0}.
--- 117,121 ----
which will create an archive file (e.g., tarball on \UNIX, ZIP file on
! Windows) containing your setup script \file{setup.py}, and your module
\file{foo.py}. The archive file will be named \file{foo-1.0.tar.gz} (or
\file{.zip}), and will unpack into a directory \file{foo-1.0}.
***************
*** 133,137 ****
This simple example demonstrates some fundamental concepts of the
! Distutils: first, both developers and installers have the same basic
user interface, i.e. the setup script. The difference is which
Distutils \emph{commands} they use: the \command{sdist} command is
--- 133,137 ----
This simple example demonstrates some fundamental concepts of the
! Distutils. First, both developers and installers have the same basic
user interface, i.e. the setup script. The difference is which
Distutils \emph{commands} they use: the \command{sdist} command is
***************
*** 156,162 ****
Other useful built distribution formats are RPM, implemented by the
\command{bdist\_rpm} command, Solaris \program{pkgtool}
! (\command{bdist\_pkgtool}, and HP-UX \program{swinstall} (\command{bdist_sdux}).
! For example, the following command will create an RPM file called
! \file{foo-1.0.noarch.rpm}:
\begin{verbatim}
--- 156,162 ----
Other useful built distribution formats are RPM, implemented by the
\command{bdist\_rpm} command, Solaris \program{pkgtool}
! (\command{bdist\_pkgtool}), and HP-UX \program{swinstall}
! (\command{bdist_sdux}). For example, the following command will
! create an RPM file called \file{foo-1.0.noarch.rpm}:
\begin{verbatim}
***************
*** 164,169 ****
\end{verbatim}
! (This uses the \command{rpm} command, so has to be run on an RPM-based
! system such as Red Hat Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by
--- 164,170 ----
\end{verbatim}
! (The \command{bdist\_rpm} command uses the \command{rpm} executable,
! therefore this has to be run on an RPM-based system such as Red Hat
! Linux, SuSE Linux, or Mandrake Linux.)
You can find out what distribution formats are available at any time by
***************
*** 210,214 ****
Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in \code{sys.path}
! can contribute modules to the root package.
\end{description}
--- 211,215 ----
Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in \code{sys.path}
! contributes modules to the root package.
\end{description}
***************
*** 278,282 ****
There are only two differences between this and the trivial one-file
distribution presented in section~\ref{simple-example}: more
! meta-data, and the specification of pure Python modules by package,
rather than by module. This is important since the Distutils consist of
a couple of dozen modules split into (so far) two packages; an explicit
--- 279,283 ----
There are only two differences between this and the trivial one-file
distribution presented in section~\ref{simple-example}: more
! metadata, and the specification of pure Python modules by package,
rather than by module. This is important since the Distutils consist of
a couple of dozen modules split into (so far) two packages; an explicit
***************
*** 295,302 ****
path, the opposite of the MacOS convention with colons.)
! This, of course, only applies to pathnames given to Distutils functions.
! If you, for example, use standard python functions such as \function{glob.glob}
! or \function{os.listdir} to specify files, you should be careful to write portable
! code instead of hardcoding path separators:
\begin{verbatim}
--- 296,304 ----
path, the opposite of the MacOS convention with colons.)
! This, of course, only applies to pathnames given to Distutils
! functions. If you, for example, use standard python functions such as
! \function{glob.glob} or \function{os.listdir} to specify files, you
! should be careful to write portable code instead of hardcoding path
! separators:
\begin{verbatim}
***************
*** 305,308 ****
--- 307,311 ----
\end{verbatim}
+
\subsection{Listing whole packages}
\label{listing-packages}
***************
*** 318,324 ****
the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might
be spelled differently on your system, but you get the idea) relative to
! the directory where your setup script lives. (If you break this
! promise, the Distutils will issue a warning but process the broken
! package anyways.)
If you use a different convention to lay out your source directory,
--- 321,327 ----
the Distutils will find a file \file{foo/\_\_init\_\_.py} (which might
be spelled differently on your system, but you get the idea) relative to
! the directory where your setup script lives. If you break this
! promise, the Distutils will issue a warning but still process the broken
! package anyways.
If you use a different convention to lay out your source directory,
***************
*** 326,330 ****
option to tell the Distutils about your convention. For example, say
you keep all Python source under \file{lib}, so that modules in the
! ``root package'' (i.e., not in any package at all) are right in
\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
and so forth. Then you would put
--- 329,333 ----
option to tell the Distutils about your convention. For example, say
you keep all Python source under \file{lib}, so that modules in the
! ``root package'' (i.e., not in any package at all) are in
\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
and so forth. Then you would put
***************
*** 384,387 ****
--- 387,391 ----
\label{describing-extensions}
+ % XXX read over this section
Just as writing Python extension modules is a bit more complicated than
writing pure Python modules, describing them to the Distutils is a bit
***************
*** 618,626 ****
to the list of exported symbols.
! \subsection{Listing scripts}
So far we have been dealing with pure and non-pure Python modules,
which are usually not run by themselves but imported by scripts.
! Scripts are files containing Python source code, indended to be
started from the command line. Scripts don't require Distutils to do
anything very complicated. The only clever feature is that if the
--- 622,630 ----
to the list of exported symbols.
! \subsection{Installing Scripts}
So far we have been dealing with pure and non-pure Python modules,
which are usually not run by themselves but imported by scripts.
! Scripts are files containing Python source code, intended to be
started from the command line. Scripts don't require Distutils to do
anything very complicated. The only clever feature is that if the
***************
*** 630,641 ****
The \option{scripts} option simply is a list of files to be handled
! in this way.
! \subsection{Listing additional files}
The \option{data\_files} option can be used to specify additional
! files needed by the module distribution: configuration files,
! data files, anything which does not fit in the previous categories.
\option{data\_files} specifies a sequence of (\var{directory},
--- 634,652 ----
The \option{scripts} option simply is a list of files to be handled
! in this way. From the PyXML setup script:
+ \begin{verbatim}
+ setup (...
+ scripts = ['scripts/xmlproc_parse', 'scripts/xmlproc_val']
+ )
+ \end{verbatim}
!
! \subsection{Installing Additional Files}
The \option{data\_files} option can be used to specify additional
! files needed by the module distribution: configuration files, message
! catalogs, data files, anything which doesn't fit in the previous
! categories.
\option{data\_files} specifies a sequence of (\var{directory},
***************
*** 645,649 ****
setup(...
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
! ('config', ['cfg/data.cfg'])])
\end{verbatim}
--- 656,662 ----
setup(...
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
! ('config', ['cfg/data.cfg']),
! ('/etc/init.d', ['init-script'])]
! )
\end{verbatim}
***************
*** 740,746 ****
\end{verbatim}
- Or consult section \ref{reference} of this document (the command
- reference).
-
Note that an option spelled \longprogramopt{foo-bar} on the command-line
is spelled \option{foo\_bar} in configuration files.
--- 753,756 ----
***************
*** 1259,1266 ****
distributions on Windows. They display a nice graphical user interface,
display some information about the module distribution to be installed taken
! from the meta-data in the setup script, let the user select a few
(currently maybe too few) options, and start or cancel the installation.
! Since the meta-data is taken from the setup script, creating
Windows installers is usually as easy as running:
--- 1269,1276 ----
distributions on Windows. They display a nice graphical user interface,
display some information about the module distribution to be installed taken
! from the metadata in the setup script, let the user select a few
(currently maybe too few) options, and start or cancel the installation.
! Since the metadata is taken from the setup script, creating
Windows installers is usually as easy as running: