[Python-checkins] CVS: python/dist/src/Doc/dist dist.tex,1.32,1.33
Fred L. Drake
fdrake@users.sourceforge.net
Thu, 01 Mar 2001 10:35:46 -0800
Update of /cvsroot/python/python/dist/src/Doc/dist
In directory usw-pr-cvs1:/tmp/cvs-serv18233/dist
Modified Files:
dist.tex
Log Message:
Comment out section titles for sections that have not been written yet;
there is no need to clutter a reader's life with those useless things.
Make the snippets of Python code conform to the standard style.
Suppress the "Contents" page for HTML; it is not needed for small documents
in the online environment since LaTeX2HTML generates lots of tables of links
anyway.
Various markup consistency nits.
Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -r1.32 -r1.33
*** dist.tex 2001/02/19 19:14:50 1.32
--- dist.tex 2001/03/01 18:35:43 1.33
***************
*** 23,28 ****
--- 23,34 ----
\end{abstract}
+ % The ugly "%begin{latexonly}" pseudo-environment supresses the table
+ % of contents for HTML generation.
+ %
+ %begin{latexonly}
\tableofcontents
+ %end{latexonly}
+
\section{Introduction}
\label{intro}
***************
*** 89,97 ****
in a file \file{foo.py}, then your setup script can be as little as
this:
\begin{verbatim}
from distutils.core import setup
! setup (name = "foo",
! version = "1.0",
! py_modules = ["foo"])
\end{verbatim}
--- 95,104 ----
in a file \file{foo.py}, then your setup script can be as little as
this:
+
\begin{verbatim}
from distutils.core import setup
! setup(name="foo",
! version="1.0",
! py_modules=["foo"])
\end{verbatim}
***************
*** 112,118 ****
--- 119,127 ----
To create a source distribution for this module, you would create a
setup script, \file{setup.py}, containing the above code, and run:
+
\begin{verbatim}
python setup.py sdist
\end{verbatim}
+
which will create an archive file (e.g., tarball on \UNIX, ZIP file on
Windows) containing your setup script, \file{setup.py}, and your module,
***************
*** 123,129 ****
--- 132,140 ----
to do is download \file{Foo-1.0.tar.gz} (or \file{.zip}), unpack it,
and---from the \file{Foo-1.0} directory---run
+
\begin{verbatim}
python setup.py install
\end{verbatim}
+
which will ultimately copy \file{foo.py} to the appropriate directory
for third-party modules in their Python installation.
***************
*** 143,149 ****
--- 154,162 ----
appropriate type of built distribution for this platform) with the
\command{bdist\_wininst} command. For example:
+
\begin{verbatim}
python setup.py bdist_wininst
\end{verbatim}
+
will create an executable installer, \file{Foo-1.0.win32.exe}, in the
current directory.
***************
*** 153,159 ****
--- 166,174 ----
command. For example, the following command will create an RPM file
called \file{Foo-1.0.noarch.rpm}:
+
\begin{verbatim}
python setup.py bdist_rpm
\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.)
***************
*** 161,164 ****
--- 176,180 ----
You can find out what distribution formats are available at any time by
running
+
\begin{verbatim}
python setup.py bdist --help-formats
***************
*** 250,263 ****
from distutils.core import setup
! setup (name = "Distutils",
! version = "1.0",
! description = "Python Distribution Utilities",
! author = "Greg Ward",
! author_email = "gward@python.net",
! url = "http://www.python.org/sigs/distutils-sig/",
!
! packages = ['distutils', 'distutils.command'],
! )
\end{verbatim}
There are only two differences between this and the trivial one-file
distribution presented in section~\ref{simple-example}: more
--- 266,279 ----
from distutils.core import setup
! setup(name="Distutils",
! version="1.0",
! description="Python Distribution Utilities",
! author="Greg Ward",
! author_email="gward@python.net",
! url="http://www.python.org/sigs/distutils-sig/",
! packages=['distutils', 'distutils.command'],
! )
\end{verbatim}
+
There are only two differences between this and the trivial one-file
distribution presented in section~\ref{simple-example}: more
***************
*** 283,286 ****
--- 299,303 ----
or os.listdir to specify files, you should be careful to write portable
code instead of hardcoding path separators:
+
\begin{verbatim}
glob.glob(os.path.join('mydir', 'subdir', '*.html'))
***************
*** 312,318 ****
--- 329,337 ----
\file{lib}, modules in the \module{foo} package are in \file{lib/foo},
and so forth. Then you would put
+
\begin{verbatim}
package_dir = {'': 'lib'}
\end{verbatim}
+
in your setup script. (The keys to this dictionary are package names,
and an empty package name stands for the root package. The values are
***************
*** 324,330 ****
--- 343,351 ----
\file{lib}, the \module{foo.bar} package in \file{lib/bar}, etc. This
would be written in the setup script as
+
\begin{verbatim}
package_dir = {'foo': 'lib'}
\end{verbatim}
+
A \code{\var{package}: \var{dir}} entry in the \option{package\_dir}
dictionary implicitly applies to all packages below \var{package}, so
***************
*** 347,353 ****
--- 368,376 ----
simplest case was shown in section~\ref{simple-example}; here is a
slightly more involved example:
+
\begin{verbatim}
py_modules = ['mod1', 'pkg.mod2']
\end{verbatim}
+
This describes two modules, one of them in the ``root'' package, the
other in the \module{pkg} package. Again, the default package/directory
***************
*** 376,390 ****
additional instructions to the compiler/linker are needed, describing
this extension is quite simple:
\begin{verbatim}
Extension("foo", ["foo.c"])
\end{verbatim}
The \class{Extension} class can be imported from
\module{distutils.core}, along with \function{setup()}. Thus, the setup
script for a module distribution that contains only this one extension
and nothing else might be:
\begin{verbatim}
from distutils.core import setup, Extension
! setup(name = "foo", version = "1.0",
! ext_modules = [Extension("foo", ["foo.c"])])
\end{verbatim}
--- 399,416 ----
additional instructions to the compiler/linker are needed, describing
this extension is quite simple:
+
\begin{verbatim}
Extension("foo", ["foo.c"])
\end{verbatim}
+
The \class{Extension} class can be imported from
\module{distutils.core}, along with \function{setup()}. Thus, the setup
script for a module distribution that contains only this one extension
and nothing else might be:
+
\begin{verbatim}
from distutils.core import setup, Extension
! setup(name="foo", version="1.0",
! ext_modules=[Extension("foo", ["foo.c"])])
\end{verbatim}
***************
*** 399,409 ****
--- 425,439 ----
The first argument to the \class{Extension} constructor is always the
name of the extension, including any package names. For example,
+
\begin{verbatim}
Extension("foo", ["src/foo1.c", "src/foo2.c"])
\end{verbatim}
+
describes an extension that lives in the root package, while
+
\begin{verbatim}
Extension("pkg.foo", ["src/foo1.c", "src/foo2.c"])
\end{verbatim}
+
describes the same extension in the \module{pkg} package. The source
files and resulting object code are identical in both cases; the only
***************
*** 414,424 ****
the same base package), use the \option{ext\_package} keyword argument
to \function{setup()}. For example,
\begin{verbatim}
setup(...
! ext_package = "pkg",
! ext_modules = [Extension("foo", ["foo.c"]),
! Extension("subpkg.bar", ["bar.c"])]
)
\end{verbatim}
will compile \file{foo.c} to the extension \module{pkg.foo}, and
\file{bar.c} to \module{pkg.subpkg.bar}.
--- 444,456 ----
the same base package), use the \option{ext\_package} keyword argument
to \function{setup()}. For example,
+
\begin{verbatim}
setup(...
! ext_package="pkg",
! ext_modules=[Extension("foo", ["foo.c"]),
! Extension("subpkg.bar", ["bar.c"])]
)
\end{verbatim}
+
will compile \file{foo.c} to the extension \module{pkg.foo}, and
\file{bar.c} to \module{pkg.subpkg.bar}.
***************
*** 459,462 ****
--- 491,495 ----
\file{include} directory under your distribution root, use the
\code{include\_dirs} option:
+
\begin{verbatim}
Extension("foo", ["foo.c"], include_dirs=["include"])
***************
*** 466,472 ****
--- 499,507 ----
extension will only be built on \UNIX{} systems with X11R6 installed to
\file{/usr}, you can get away with
+
\begin{verbatim}
Extension("foo", ["foo.c"], include_dirs=["/usr/include/X11"])
\end{verbatim}
+
You should avoid this sort of non-portable usage if you plan to
distribute your code: it's probably better to write your code to include
***************
*** 486,489 ****
--- 521,525 ----
though, you can find that directory using the Distutils
\module{sysconfig} module:
+
\begin{verbatim}
from distutils.sysconfig import get_python_inc
***************
*** 492,495 ****
--- 528,532 ----
Extension(..., include_dirs=[incdir]))
\end{verbatim}
+
Even though this is quite portable---it will work on any Python
installation, regardless of platform---it's probably easier to just
***************
*** 507,510 ****
--- 544,548 ----
For example:
+
\begin{verbatim}
Extension(...,
***************
*** 513,517 ****
--- 551,557 ----
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
\end{verbatim}
+
is the equivalent of having this at the top of every C source file:
+
\begin{verbatim}
#define NDEBUG 1
***************
*** 533,536 ****
--- 573,577 ----
For example, if you need to link against libraries known to be in the
standard library search path on target systems
+
\begin{verbatim}
Extension(...,
***************
*** 540,543 ****
--- 581,585 ----
If you need to link with libraries in a non-standard location, you'll
have to include the location in \code{library\_dirs}:
+
\begin{verbatim}
Extension(...,
***************
*** 545,548 ****
--- 587,591 ----
libraries=["X11", "Xt"])
\end{verbatim}
+
(Again, this sort of non-portable construct should be avoided if you
intend to distribute your code.)
***************
*** 585,588 ****
--- 628,632 ----
\subsection{Listing additional files}
+
The \option{data\_files} option can be used to specify additional
files needed by the module distribution: configuration files,
***************
*** 591,594 ****
--- 635,639 ----
\option{data\_files} specify a sequence of \code{(directory, files)}
pairs in the following way:
+
\begin{verbatim}
setup(...
***************
*** 626,632 ****
or stable enough yet for real-world use.)
- \XXX{should reference description of distutils config files in
- ``Installing'' manual here}
-
The setup configuration file is a useful middle-ground between the setup
script---which, ideally, would be opaque to installers\footnote{This
--- 671,674 ----
***************
*** 648,651 ****
--- 690,694 ----
The basic syntax of the configuration file is simple:
+
\begin{verbatim}
[command]
***************
*** 653,656 ****
--- 696,700 ----
...
\end{verbatim}
+
where \var{command} is one of the Distutils commands (e.g.
\command{build\_py}, \command{install}), and \var{option} is one of the
***************
*** 663,666 ****
--- 707,711 ----
You can find out the list of options supported by a particular command
with the universal \longprogramopt{help} option, e.g.
+
\begin{verbatim}
> python setup.py --help build_ext
***************
*** 676,679 ****
--- 721,725 ----
[...]
\end{verbatim}
+
Or consult section \ref{reference} of this document (the command
reference).
***************
*** 688,702 ****
--- 734,752 ----
\module{pkg.mod1} and \module{pkg.mod2}. You can always use the
\longprogramopt{inplace} option on the command-line to ensure this:
+
\begin{verbatim}
python setup.py build_ext --inplace
\end{verbatim}
+
But this requires that you always specify the \command{build\_ext}
command explicitly, and remember to provide \longprogramopt{inplace}.
An easier way is to ``set and forget'' this option, by encoding it in
\file{setup.cfg}, the configuration file for this distribution:
+
\begin{verbatim}
[build_ext]
inplace=1
\end{verbatim}
+
This will affect all builds of this module distribution, whether or not
you explcitly specify \command{build\_ext}. If you include
***************
*** 718,721 ****
--- 768,772 ----
command-line for every run. Hence, here is a snippet from the
Distutils' own \file{setup.cfg}:
+
\begin{verbatim}
[bdist_rpm]
***************
*** 728,735 ****
--- 779,794 ----
examples/
\end{verbatim}
+
Note that the \option{doc\_files} option is simply a
whitespace-separated string split across multiple lines for readability.
+ \begin{seealso}
+ \seetitle[../inst/config-syntax.html]{Installing Python
+ Modules}{More information on the configuration files is
+ available in the manual for system administrators.}
+ \end{seealso}
+
+
\section{Creating a Source Distribution}
\label{source-dist}
***************
*** 738,744 ****
--- 797,805 ----
\command{sdist} command to create a source distribution. In the
simplest case,
+
\begin{verbatim}
python setup.py sdist
\end{verbatim}
+
(assuming you haven't specified any \command{sdist} options in the setup
script or config file), \command{sdist} creates the archive of the
***************
*** 749,755 ****
--- 810,818 ----
You can specify as many formats as you like using the
\longprogramopt{formats} option, for example:
+
\begin{verbatim}
python setup.py sdist --formats=gztar,zip
\end{verbatim}
+
to create a gzipped tarball and a zip file. The available formats are:
\begin{tableiii}{l|l|c}{code}%
***************
*** 811,814 ****
--- 874,878 ----
distribution. For an example, again we turn to the Distutils' own
manifest template:
+
\begin{verbatim}
include *.txt
***************
*** 816,819 ****
--- 880,884 ----
prune examples/sample?/build
\end{verbatim}
+
The meanings should be fairly clear: include all files in the
distribution root matching \code{*.txt}, all files anywhere under the
***************
*** 906,909 ****
--- 971,975 ----
existing pattern in the manifest template, you should regenerate the
manifest:
+
\begin{verbatim}
python setup.py sdist --force-manifest
***************
*** 912,918 ****
--- 978,986 ----
Or, you might just want to (re)generate the manifest, but not create a
source distribution:
+
\begin{verbatim}
python setup.py sdist --manifest-only
\end{verbatim}
+
\longprogramopt{manifest-only} implies \longprogramopt{force-manifest}.
\programopt{-o} is a shortcut for \longprogramopt{manifest-only}, and
***************
*** 954,960 ****
--- 1022,1030 ----
As a simple example, if I run the following command in the Distutils
source tree:
+
\begin{verbatim}
python setup.py bdist
\end{verbatim}
+
then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the \file{build}
***************
*** 984,990 ****
--- 1054,1062 ----
similar to the \command{sdist} command, which you can use to select the
types of built distribution to generate: for example,
+
\begin{verbatim}
python setup.py bdist --format=zip
\end{verbatim}
+
would, when run on a \UNIX{} system, create
\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
***************
*** 1055,1069 ****
--- 1127,1146 ----
The usual way to create an RPM of your module distribution is to run the
\command{bdist\_rpm} command:
+
\begin{verbatim}
python setup.py bdist_rpm
\end{verbatim}
+
or the \command{bdist} command with the \longprogramopt{format} option:
+
\begin{verbatim}
python setup.py bdist --formats=rpm
\end{verbatim}
+
The former allows you to specify RPM-specific options; the latter allows
you to easily specify multiple formats in one run. If you need to do
both, you can explicitly specify multiple \command{bdist\_*} commands
and their options:
+
\begin{verbatim}
python setup.py bdist_rpm --packager="John Doe <jdoe@python.net>" \
***************
*** 1144,1147 ****
--- 1221,1225 ----
\longprogramopt{spec-only}, this gives you an opportunity to customize
the \file{.spec} file manually:
+
\begin{verbatim}
> python setup.py bdist_rpm --spec-only
***************
*** 1149,1152 ****
--- 1227,1231 ----
> python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
\end{verbatim}
+
(Although a better way to do this is probably to override the standard
\command{bdist\_rpm} command with one that writes whatever else you want
***************
*** 1166,1173 ****
--- 1245,1255 ----
Since the meta-data is taken from the setup script, creating
Windows installers is usually as easy as running:
+
\begin{verbatim}
python setup.py bdist_wininst
\end{verbatim}
+
or the \command{bdist} command with the \longprogramopt{format} option:
+
\begin{verbatim}
python setup.py bdist --formats=wininst
***************
*** 1191,1230 ****
the \longprogramopt{no-target-optimize} option.
! \section{Examples}
! \label{examples}
! \subsection{Pure Python distribution (by module)}
! \label{pure-mod}
! \subsection{Pure Python distribution (by package)}
! \label{pure-pkg}
! \subsection{Single extension module}
! \label{single-ext}
! \subsection{Multiple extension modules}
! \label{multiple-ext}
! \subsection{Putting it all together}
! \section{Extending the Distutils}
! \label{extending}
! \subsection{Extending existing commands}
! \label{extend-existing}
! \subsection{Writing new commands}
! \label{new-commands}
! \XXX{Would an uninstall command be a good example here?}
--- 1273,1312 ----
the \longprogramopt{no-target-optimize} option.
! %\section{Examples}
! %\label{examples}
! %\subsection{Pure Python distribution (by module)}
! %\label{pure-mod}
! %\subsection{Pure Python distribution (by package)}
! %\label{pure-pkg}
! %\subsection{Single extension module}
! %\label{single-ext}
! %\subsection{Multiple extension modules}
! %\label{multiple-ext}
! %\subsection{Putting it all together}
! %\section{Extending the Distutils}
! %\label{extending}
! %\subsection{Extending existing commands}
! %\label{extend-existing}
! %\subsection{Writing new commands}
! %\label{new-commands}
! %\XXX{Would an uninstall command be a good example here?}
***************
*** 1234,1251 ****
! \subsection{Building modules: the \protect\command{build} command family}
! \label{build-cmds}
! \subsubsection{\protect\command{build}}
! \label{build-cmd}
! \subsubsection{\protect\command{build\_py}}
! \label{build-py-cmd}
! \subsubsection{\protect\command{build\_ext}}
! \label{build-ext-cmd}
! \subsubsection{\protect\command{build\_clib}}
! \label{build-clib-cmd}
--- 1316,1333 ----
! %\subsection{Building modules: the \protect\command{build} command family}
! %\label{build-cmds}
! %\subsubsection{\protect\command{build}}
! %\label{build-cmd}
! %\subsubsection{\protect\command{build\_py}}
! %\label{build-py-cmd}
! %\subsubsection{\protect\command{build\_ext}}
! %\label{build-ext-cmd}
! %\subsubsection{\protect\command{build\_clib}}
! %\label{build-clib-cmd}
***************
*** 1258,1263 ****
\command{install\_scripts}.
! \subsubsection{\protect\command{install\_lib}}
! \label{install-lib-cmd}
\subsubsection{\protect\command{install\_data}}
--- 1340,1345 ----
\command{install\_scripts}.
! %\subsubsection{\protect\command{install\_lib}}
! %\label{install-lib-cmd}
\subsubsection{\protect\command{install\_data}}
***************
*** 1270,1275 ****
! \subsection{Cleaning up: the \protect\command{clean} command}
! \label{clean-cmd}
--- 1352,1357 ----
! %\subsection{Cleaning up: the \protect\command{clean} command}
! %\label{clean-cmd}
***************
*** 1310,1332 ****
\XXX{Windows and MacOS support not there yet}
-
- \subsection{Creating a ``built'' distribution: the
- \protect\command{bdist} command family}
- \label{bdist-cmds}
-
-
- \subsubsection{\protect\command{blib}}
-
- \subsubsection{\protect\command{blib\_dumb}}
-
- \subsubsection{\protect\command{blib\_rpm}}
-
- \subsubsection{\protect\command{blib\_wise}}
--- 1392,1408 ----
\XXX{Windows and MacOS support not there yet}
+ %\subsection{Creating a built distribution: the
+ % \protect\command{bdist} command family}
+ %\label{bdist-cmds}
+ %\subsubsection{\protect\command{blib}}
+ %\subsubsection{\protect\command{blib\_dumb}}
+ %\subsubsection{\protect\command{blib\_rpm}}
+ %\subsubsection{\protect\command{blib\_wise}}