mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-02 03:01:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 15

Lots of small markup adjustments for consistency with the rest of the

Browse source 
documentation.
This commit is contained in:
Fred Drake 2000-10-26 16:41:03 +00:00
parent 35f8d46f94
commit eff9a87fcc
2 changed files with 72 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

49
Doc/dist/dist.tex vendored
View file

@ -116,7 +116,7 @@ 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
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}.
@ -194,12 +194,12 @@ following glossary of common Python terms:
single \file{.py} file (and possibly associated \file{.pyc} and/or
\file{.pyo} files). Sometimes referred to as a ``pure module.''
\item[extension module] a module written in the low-level language of
the Python implemention: C/C++ for CPython, Java for JPython.
the Python implemention: C/C++ for Python, Java for JPython.
Typically contained in a single dynamically loadable pre-compiled
file, e.g. a shared object (\file{.so}) file for CPython extensions on
Unix, a DLL (given the \file{.pyd} extension) for CPython extensions
file, e.g. a shared object (\file{.so}) file for Python extensions on
\UNIX, a DLL (given the \file{.pyd} extension) for Python extensions
on Windows, or a Java class file for JPython extensions. (Note that
currently, the Distutils only handles C/C++ extensions for CPython.)
currently, the Distutils only handles C/C++ extensions for Python.)
\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}.
@ -282,15 +282,15 @@ list of every module would be tedious to generate and difficult to
maintain.
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
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 programmers should keep in
this document are slash-separated (MacOS 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).
path, the opposite of the MacOS convention with colons).
\subsection{Listing whole packages}
@ -436,7 +436,7 @@ The second argument to the \class{Extension} constructor is a list of
source files. Since the Distutils currently only support C/C++
extensions, these are normally C/C++ source files. (Be sure to use
appropriate extensions to distinguish C++ source files: \file{.cc} and
\file{.cpp} seem to be recognized by both Unix and Windows compilers.)
\file{.cpp} seem to be recognized by both \UNIX{} and Windows compilers.)
However, you can also include SWIG interface (\file{.i}) files in the
list; the \command{build\_ext} command knows how to deal with SWIG
@ -468,7 +468,7 @@ Extension("foo", ["foo.c"], include_dirs=["include"])
\end{verbatim}
You can specify absolute directories there; if you know that your
extension will only be built on Unix systems with X11R6 installed to
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"])
@ -480,7 +480,7 @@ distribute your code: it's probably better to write your code to include
If you need to include header files from some other Python extension,
you can take advantage of the fact that the Distutils install extension
header files in a consistent way. For example, the Numerical Python
header files are installed (on a standard Unix installation) to
header files are installed (on a standard \UNIX{} installation) to
\file{/usr/local/include/python1.5/Numerical}. (The exact location will
differ according to your platform and Python installation.) Since the
Python include directory---\file{/usr/local/include/python1.5} in this
@ -634,7 +634,7 @@ is spelled \option{foo\_bar} in configuration files.
For example, say you want your extensions to be built
``in-place''---that is, you have an extension \module{pkg.ext}, and you
want the compiled extension file (\file{ext.so} on Unix, say) to be put
want the compiled extension file (\file{ext.so} on \UNIX, say) to be put
in the same source directory as your pure Python modules
\module{pkg.mod1} and \module{pkg.mod2}. You can always use the
\longprogramopt{inplace} option on the command-line to ensure this:
@ -694,8 +694,8 @@ python setup.py sdist
(assuming you haven't specified any \command{sdist} options in the setup
script or config file), \command{sdist} creates the archive of the
default format for the current platform. The default format is gzip'ed
tar file (\file{.tar.gz}) on Unix, and ZIP file on Windows. \XXX{no Mac
OS support here}
tar file (\file{.tar.gz}) on \UNIX, and ZIP file on Windows.
\XXX{no MacOS support here}
You can specify as many formats as you like using the
\longprogramopt{formats} option, for example:
@ -715,7 +715,7 @@ to create a gzipped tarball and a zip file. The available formats are:
\noindent Notes:
\begin{description}
\item[(1)] default on Windows
\item[(2)] default on Unix
\item[(2)] default on \UNIX
\item[(3)] requires either external \program{zip} utility or
\module{zipfile} module (not part of the standard Python library)
\item[(4)] requires external utilities: \program{tar} and possibly one
@ -911,11 +911,11 @@ then the Distutils builds my module distribution (the Distutils itself
in this case), does a ``fake'' installation (also in the \file{build}
directory), and creates the default type of built distribution for my
platform. The default format for built distributions is a ``dumb'' tar
file on Unix, and an simple executable installer on Windows. (That tar
file on \UNIX, and an simple executable installer on Windows. (That tar
file is considered ``dumb'' because it has to be unpacked in a specific
location to work.)
Thus, the above command on a Unix system creates
Thus, the above command on a \UNIX{} system creates
\file{Distutils-0.9.1.\filevar{plat}.tar.gz}; unpacking this tarball
from the right place installs the Distutils just as though you had
downloaded the source distribution and run \code{python setup.py
@ -937,7 +937,7 @@ 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
would, when run on a \UNIX{} system, create
\file{Distutils-0.8.\filevar{plat}.zip}---again, this archive would be
unpacked from the root directory to install the Distutils.
@ -956,7 +956,7 @@ The available formats for built distributions are:
\noindent Notes:
\begin{description}
\item[(1)] default on Unix
\item[(1)] default on \UNIX
\item[(2)] default on Windows \XXX{to-do!}
\item[(3)] requires external utilities: \program{tar} and possibly one
of \program{gzip}, \program{bzip2}, or \program{compress}
@ -1195,7 +1195,8 @@ This command installs all (Python) scripts in the distribution.
\label{clean-cmd}
\subsection{Creating a source distribution: the \protect\command{sdist} command}
\subsection{Creating a source distribution: the
\protect\command{sdist} command}
\label{sdist-cmd}
@ -1220,15 +1221,15 @@ The manifest template commands are:
\lineii{prune \var{dir}}{exclude all files under \var{dir}}
\lineii{graft \var{dir}}{include all files under \var{dir}}
\end{tableii}
The patterns here are Unix-style ``glob'' patterns: \code{*} matches any
The patterns here are \UNIX-style ``glob'' patterns: \code{*} matches any
sequence of regular filename characters, \code{?} matches any single
regular filename character, and \code{[\var{range}]} matches any of the
characters in \var{range} (e.g., \code{a-z}, \code{a-zA-Z},
\code{a-f0-9\_.}). The definition of ``regular filename character'' is
platform-specific: on Unix it is anything except slash; on Windows
anything except backslash or colon; on Mac OS anything except colon.
platform-specific: on \UNIX{} it is anything except slash; on Windows
anything except backslash or colon; on MacOS anything except colon.
\XXX{Windows and Mac OS support not there yet}
\XXX{Windows and MacOS support not there yet}
\subsection{Creating a ``built'' distribution: the

93
Doc/inst/inst.tex
View file

@ -140,20 +140,20 @@ inadequate and targeted at experienced Python developers. Such users
are already familiar with how the Python library is laid out on their
platform, and know where to copy various files in order for Python to
find them. This document makes no such assumptions, and explains how
the Python library is laid out on three major platforms (Unix, Windows,
and Mac~OS), so that you can understand what happens when the Distutils
the Python library is laid out on three major platforms (\UNIX, Windows,
and MacOS), so that you can understand what happens when the Distutils
do their job \emph{and} know how to install modules manually when the
module author fails to provide a setup script.
Additionally, while there has not previously been a standard
installation mechanism, Python has had some standard machinery for
building extensions on Unix since Python \XXX{version?}. This machinery
(the \file{Makefile.pre.in} file) is superseded by the Distutils, but it
will no doubt live on in older module distributions for a while. This
\file{Makefile.pre.in} mechanism is documented in the ``Extending \&
Embedding Python'' manual, but that manual is aimed at module
developers---hence, we include documentation for builders/installers
here.
building extensions on \UNIX{} since Python \XXX{version?}. This
machinery (the \file{Makefile.pre.in} file) is superseded by the
Distutils, but it will no doubt live on in older module distributions
for a while. This \file{Makefile.pre.in} mechanism is documented in
the \citetitle[../ext/ext.html]{Extending \& Embedding Python} manual,
but that manual is aimed at module developers---hence, we include
documentation for builders/installers here.
All of the pre-Distutils material is tucked away in
section~\ref{pre-distutils}.
@ -167,9 +167,9 @@ a module distribution using the Distutils is usually one simple command:
\begin{verbatim}
python setup.py install
\end{verbatim}
On Unix, you'd run this command from a shell prompt; on Windows, you
On \UNIX, you'd run this command from a shell prompt; on Windows, you
have to open a command prompt window (``DOS box'') and do it there; on
Mac~OS, things are a tad more complicated (see below).
MacOS, things are a tad more complicated (see below).
\subsection{Platform variations}
@ -178,8 +178,8 @@ Mac~OS, things are a tad more complicated (see below).
You should always run the setup command from the distribution root
directory, i.e. the top-level subdirectory that the module source
distribution unpacks into. For example, if you've just downloaded a
module source distribution \file{foo-1.0.tar.gz} onto a Unix system, the
normal thing to do is:
module source distribution \file{foo-1.0.tar.gz} onto a
\UNIX{} system, the normal thing to do is:
\begin{verbatim}
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
@ -198,7 +198,7 @@ cd c:\Temp\foo-1.0
python setup.py install
\end{verbatim}
On Mac~OS, you have to go through a bit more effort to supply
On MacOS, you have to go through a bit more effort to supply
command-line arguments to the setup script:
\begin{itemize}
\item hit option-double-click on the script's icon (or option-drop it
@ -209,8 +209,9 @@ command-line arguments to the setup script:
voluminous and often useful)
\item when the command-line dialog pops up, enter ``install'' (you
can, of course, enter any Distutils command-line as described in this
document or in the ``Distributing Python Modules'' document: just
leave of the initial \code{python setup.py} and you'll be fine)
document or in \citetitle[../dist/dist.html]{Distributing Python
Modules}: just leave off the initial \code{python setup.py} and
you'll be fine)
\end{itemize}
\XXX{this should change: every Distutils setup script will need
command-line arguments for every run (and should probably keep stdout
@ -300,15 +301,15 @@ If you don't choose an installation directory---i.e., if you just run
\code{setup.py install}---then the \command{install} command installs to
the standard location for third-party Python modules. This location
varies by platform and by how you built/installed Python itself. On
Unix and Mac~OS, it also depends on whether the module distribution
\UNIX{} and MacOS, it also depends on whether the module distribution
being installed is pure Python or contains extensions (``non-pure''):
\begin{tableiv}{l|l|l|c}{textrm}%
{Platform}{Standard installation location}{Default value}{Notes}
\lineiv{Unix (pure)}
\lineiv{\UNIX{} (pure)}
{\filenq{\filevar{prefix}/lib/python2.0/site-packages}}
{\filenq{/usr/local/lib/python2.0/site-packages}}
{(1)}
\lineiv{Unix (non-pure)}
\lineiv{\UNIX{} (non-pure)}
{\filenq{\filevar{exec-prefix}/lib/python2.0/site-packages}}
{\filenq{/usr/local/lib/python2.0/site-packages}}
{(1)}
@ -316,11 +317,11 @@ being installed is pure Python or contains extensions (``non-pure''):
{\filenq{\filevar{prefix}}}
{\filenq{C:\textbackslash{}Python}}
{(2)}
\lineiv{Mac~OS (pure)}
\lineiv{MacOS (pure)}
{\filenq{\filevar{prefix}:Lib:site-packages}}
{\filenq{Python:Lib:site-packages}}
{}
\lineiv{Mac~OS (non-pure)}
\lineiv{MacOS (non-pure)}
{\filenq{\filevar{prefix}:Lib:site-packages}}
{\filenq{Python:Lib:site-packages}}
{}
@ -331,7 +332,7 @@ being installed is pure Python or contains extensions (``non-pure''):
\item[(1)] Most Linux distributions include Python as a standard part of
the system, so \filevar{prefix} and \filevar{exec-prefix} are usually
both \file{/usr} on Linux. If you build Python yourself on Linux (or
any Unix-like system), the default \filevar{prefix} and
any \UNIX-like system), the default \filevar{prefix} and
\filevar{exec-prefix} are \file{/usr/local}.
\item[(2)] The default installation directory on Windows was
\file{C:\textbackslash{}Program Files\textbackslash{}Python} under
@ -340,12 +341,12 @@ being installed is pure Python or contains extensions (``non-pure''):
\filevar{prefix} and \filevar{exec-prefix} stand for the directories
that Python is installed to, and where it finds its libraries at
run-time. They are always the same under Windows and Mac~OS, and very
often the same under Unix. You can find out what your Python
run-time. They are always the same under Windows and MacOS, and very
often the same under \UNIX. You can find out what your Python
installation uses for \filevar{prefix} and \filevar{exec-prefix} by
running Python in interactive mode and typing a few simple commands.
Under Unix, just type \code{python} at the shell prompt; under Windows,
run ``Python 2.0 (interpreter)'' \XXX{right?}; under Mac~OS, \XXX{???}.
Under \UNIX, just type \code{python} at the shell prompt; under Windows,
run ``Python 2.0 (interpreter)'' \XXX{right?}; under MacOS, \XXX{???}.
Once the interpreter is started, you type Python code at the
\samp{>>> } prompt. For example, on my Linux system, I type the three
Python statements shown below, and get the output as shown, to find
@ -400,7 +401,7 @@ section~\ref{custom-install} on custom installations.
(This is the section to read for people doing any sort of interesting
build. Things to talk about:
\begin{itemize}
\item the \file{Setup} file (any platform now, but Unix-biased)
\item the \file{Setup} file (any platform now, but \UNIX-biased)
\item CFLAGS and LDFLAGS (must implement them first!)
\item using non-MS compilers on Windows (how to convert
Python's library, ...)
@ -423,7 +424,7 @@ build. Things to talk about:
Often, it is necessary or desirable to install modules to a location
other than the standard location for third-party Python modules. For
example, on a Unix system you might not have permission to write to the
example, on a \UNIX{} system you might not have permission to write to the
standard third-party module directory. Or you might wish to try out a
module before making it a standard part of your local Python
installation; this is especially true when upgrading a distribution
@ -439,12 +440,12 @@ install files. The details differ across platforms, so read whichever
of the following section applies to you.
\subsection{Alternate installation: Unix (the home scheme)}
\subsection{Alternate installation: \UNIX{} (the home scheme)}
\label{alt-install-prefix}
Under Unix, there are two ways to perform an alternate installation.
Under \UNIX, there are two ways to perform an alternate installation.
The ``prefix scheme'' is similar to how alternate installation works
under Windows and Mac~OS, but is not necessarily the most useful way to
under Windows and MacOS, but is not necessarily the most useful way to
maintain a personal Python library. Hence, we document the more
convenient and commonly useful ``home scheme'' first.
@ -469,7 +470,7 @@ installation base as follows:
{home}{/bin}
{home}{/share}
\subsection{Alternate installation: Unix (the prefix scheme)}
\subsection{Alternate installation: \UNIX{} (the prefix scheme)}
\label{alt-install-home}
The ``prefix scheme'' is useful when you wish to use one Python
@ -521,7 +522,7 @@ installation; if the directories listed above do not already exist, they
are created at installation time.
Incidentally, the real reason the prefix scheme is important is simply
that a standard Unix installation uses the prefix scheme, but with
that a standard \UNIX{} installation uses the prefix scheme, but with
\longprogramopt{prefix} and \longprogramopt{exec-prefix} supplied by
Python itself (as \code{sys.prefix} and \code{sys.exec\_prefix}). Thus,
you might think you'll never use the prefix scheme, but every time you
@ -546,7 +547,7 @@ point to an alternate Python installation, this is immaterial.)
Since Windows has no conception of a user's home directory, and since
the standard Python installation under Windows is simpler than that
under Unix, there's no point in having separate \longprogramopt{prefix}
under \UNIX, there's no point in having separate \longprogramopt{prefix}
and \longprogramopt{home} options. Just use the \longprogramopt{prefix}
option to specify a base directory, e.g.
\begin{verbatim}
@ -564,10 +565,10 @@ Files are installed as follows:
{prefix}{\textbackslash{}Data}
\subsection{Alternate installation: Mac~OS}
\subsection{Alternate installation: MacOS}
\label{alt-install-macos}
Like Windows, Mac~OS has no notion of home directories (or even of
Like Windows, MacOS has no notion of home directories (or even of
users), and a fairly simple standard Python installation. Thus, only a
\longprogramopt{prefix} option is needed. It defines the installation
base, and files are installed under it as follows:
@ -597,11 +598,11 @@ how you define a custom installation scheme. These override options can
be relative, absolute, or explicitly defined in terms of one of the
installation base directories. (There are two installation base
directories, and they are normally the same---they only differ when you
use the Unix ``prefix scheme'' and supply different
use the \UNIX{} ``prefix scheme'' and supply different
\longprogramopt{prefix} and \longprogramopt{exec-prefix} options.)
For example, say you're installing a module distribution to your home
directory under Unix---but you want scripts to go in
directory under \UNIX---but you want scripts to go in
\file{\textasciitilde/scripts} rather than \file{\textasciitilde/bin}.
As you might expect, you can override this directory with the
\longprogramopt{install-scripts} option; in this case, it makes most
@ -611,7 +612,7 @@ the installation base directory (your home directory, in this case):
python setup.py install --home=~ --install-scripts=scripts
\end{verbatim}
Another Unix example: suppose your Python installation was built and
Another \UNIX{} example: suppose your Python installation was built and
installed with a prefix of \file{/usr/local/python}, so under a standard
installation scripts will wind up in \file{/usr/local/python/bin}. If
you want them in \file{/usr/local/bin} instead, you would supply this
@ -703,10 +704,10 @@ that have such a notion---but the Distutils additionally define a few
extra variables that may not be in your environment, such as
\code{\$PLAT}. (And of course, you can only use the configuration
variables supplied by the Distutils on systems that don't have
environment variables, such as Mac~OS (\XXX{true?}).) See
environment variables, such as MacOS (\XXX{true?}).) See
section~\ref{config-files} for details.
\XXX{need some Windows and Mac~OS examples---when would custom
\XXX{need some Windows and MacOS examples---when would custom
installation schemes be needed on those platforms?}
@ -727,7 +728,7 @@ apply, values from ``earlier'' files are overridden by ``later'' files.
\label{sec:config-filenames}
The names and locations of the configuration files vary slightly across
platforms. On Unix, the three configuration files (in the order they
platforms. On \UNIX, the three configuration files (in the order they
are processed) are:
\begin{tableiii}{l|l|c}{textrm}
{Type of file}{Location and filename}{Notes}
@ -744,7 +745,7 @@ On Windows, the configuration files are:
\lineiii{local}{\filenq{setup.cfg}}{(3)}
\end{tableiii}
And on Mac~OS, they are:
And on MacOS, they are:
\begin{tableiii}{l|l|c}{textrm}
{Type of file}{Location and filename}{Notes}
\lineiii{system}{\filenq{\filevar{prefix}:Lib:distutils:pydistutils.cfg}}{(6)}
@ -756,12 +757,12 @@ And on Mac~OS, they are:
\begin{description}
\item[(1)] Strictly speaking, the system-wide configuration file lives
in the directory where the Distutils are installed; under Python 1.6
and later on Unix, this is as shown. For Python 1.5.2, the Distutils
and later on \UNIX, this is as shown. For Python 1.5.2, the Distutils
will normally be installed to
\file{\filevar{prefix}/lib/site-packages/python1.5/distutils},
so the system configuration file should be put there under Python
1.5.2.
\item[(2)] On Unix, if the \envvar{HOME} environment variable is not
\item[(2)] On \UNIX, if the \envvar{HOME} environment variable is not
defined, the user's home directory will be determined with the
\function{getpwuid()} function from the standard \module{pwd} module.
\item[(3)] I.e., in the current directory (usually the location of the
@ -783,7 +784,7 @@ And on Mac~OS, they are:
\item[(6)] (See also notes (1) and (4).) The default installation
prefix is just \file{Python:}, so under Python 1.6 and later this is
normally\file{Python:Lib:distutils:pydistutils.cfg}. (The Distutils
don't work very well with Python 1.5.2 under Mac~OS. \XXX{true?})
don't work very well with Python 1.5.2 under MacOS. \XXX{true?})
\end{description}