[Python-checkins] python/nondist/sandbox/distutilsref distref.tex,1.3,1.4
anthonybaxter@users.sourceforge.net
anthonybaxter@users.sourceforge.net
Tue, 13 May 2003 04:36:41 -0700
Update of /cvsroot/python/python/nondist/sandbox/distutilsref
In directory sc8-pr-cvs1:/tmp/cvs-serv12355
Modified Files:
distref.tex
Log Message:
Extenstion arguments in distutils.core section.
Index: distref.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/distutilsref/distref.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** distref.tex 13 May 2003 10:14:14 -0000 1.3
--- distref.tex 13 May 2003 11:36:39 -0000 1.4
***************
*** 1,10 ****
! \chapter{Building and installing Python modules, the Compleat Reference.}
!
- %\sectionauthor {Anthony Baxter}{anthony@interlink.com.au}
%\sectionauthor {Greg Ward}{gward@python.net}
\index{distutils}
\declaremodule{standard}{distutils}
The \module{distutils} package provides support for building and
--- 1,12 ----
! \chapter{Building and Installing Python modules}
%\sectionauthor {Greg Ward}{gward@python.net}
+ %\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+ %\sectionauthor {Anthony Baxter}{anthony@interlink.com.au}
\index{distutils}
\declaremodule{standard}{distutils}
+ \modulesynopsis{Support for building and installing Python modules
+ into an existing Python installation}
The \module{distutils} package provides support for building and
***************
*** 12,19 ****
modules may be either 100\%{}-pure Python, or may be extension modules
written in C, or may be collections of Python packages which include
! modules coded in both Python and C.
\localmoduletable
\section{The simple interface}
--- 14,46 ----
modules may be either 100\%{}-pure Python, or may be extension modules
written in C, or may be collections of Python packages which include
! modules coded in both Python and C. The \module{distutils} package
! also provides support for building source and binary distributions
! of packages in a variety of formats, suitable for distribution separately
! to Python.
!
! As well as this reference documentation, there are two separate
! documents that discuss \module{distutils}. To learn about distributing new
! modules using the \module{distutils} facilities, read
! \citetitle[../dist/dist.html]{Distributing Python Modules}. To learn
! about installing Python modules, whether or not the author made use of
! the \module{distutils} package, read
! \citetitle[../inst/inst.html]{Installing Python Modules}.
\localmoduletable
+ \begin{seealso}
+ \seetitle[../dist/dist.html]{Distributing Python Modules}{The manual
+ for developers and packagers of Python modules. This
+ describes how to prepare \module{distutils}-based packages
+ so that they may be easily installed into an existing
+ Python installaion.}
+
+ \seetitle[../inst/inst.html]{Installing Python Modules}{An
+ ``administrators'' manual which includes information on
+ installing modules into an existing Python installation.
+ You do not need to be a Python programmer to read this
+ manual.}
+ \end{seealso}
+
\section{The simple interface}
***************
*** 37,41 ****
are laid out in the following table.
! \begin{tableiii}{c|l|l}{argument name}{argument name}{value}{notes}
\lineiii{name}{The name of the package}{a string}
\lineiii{version}{The version number of the package}{See \refmodule{distutils.version}}
--- 64,68 ----
are laid out in the following table.
! \begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
\lineiii{name}{The name of the package}{a string}
\lineiii{version}{The version number of the package}{See \refmodule{distutils.version}}
***************
*** 63,83 ****
\end{tableiii}
- In addition, the \module{distutils.core} module exposed a number of
- other classes that live elsewhere.
-
- \begin{itemize}
- \item The \class{Distribution} from \refmodule{distutils.dist}
- \item The \class{Command} from \refmodule{distutils.cmd}
- \item The \class{Extension} from \refmodule{distutils.extension}
- \end{itemize}
-
- A short description of each of these follows, but see the relevant
- module for the full reference.
-
-
-
\end{funcdesc}
-
\begin{funcdesc}{run_setup}{script_name, script_args=None, stop_after='run'}
Run a setup script in a somewhat controlled environment, and return
--- 90,95 ----
***************
*** 109,112 ****
--- 121,201 ----
\end{funcdesc}
+ In addition, the \module{distutils.core} module exposed a number of
+ classes that live elsewhere.
+
+ \begin{itemize}
+ \item \class{Extension} from \refmodule{distutils.extension}
+ \item \class{Command} from \refmodule{distutils.cmd}
+ \item \class{Distribution} from \refmodule{distutils.dist}
+ \end{itemize}
+
+ A short description of each of these follows, but see the relevant
+ module for the full reference.
+
+ \begin{classdesc*}{Extension}
+
+ The Extension class describes a single C or C++ extension module in a
+ setup script. It accepts the following keyword arguments in it's constructor
+
+ \begin{tableiii}{c|l|l}{argument name}{argument name}{value}{type}
+ \lineiii{name}{the full name of the extension, including any packages
+ -- ie. *not* a filename or pathname, but Python dotted name}{string}
+ \lineiii{sources}{list of source filenames, relative to the distribution
+ root (where the setup script lives), in Unix form (slash-separated) for
+ portability. Source files may be C, C++, SWIG (.i), platform-specific
+ resource files, or whatever else is recognized by the "build_ext"
+ command as source for a Python extension.}{string}
+ \lineiii{include_dirs}{list of directories to search for C/C++ header
+ files (in \UNIX form for portability)}{string}
+ \lineiii{define_macros}{list of macros to define; each macro is defined
+ using a 2-tuple, where 'value' is either the string to define it to or
+ None to define it without a particular value (equivalent of "\#define
+ FOO" in source or -DFOO on Unix C compiler command line) }{ (string,string)
+ tuple or (name,\code{None}) }
+ \lineiii{undef_macros}{list of macros to undefine explicitly}{string}
+ \lineiii{library_dirs}{list of directories to search for C/C++ libraries
+ at link time }{string}
+ \lineiii{libraries}{list of library names (not filenames or paths) to
+ link against }{string}
+ \lineiii{runtime_library_dirs}{list of directories to search for C/C++
+ libraries at run time (for shared extensions, this is when the extension
+ is loaded)}{string}
+ \lineiii{extra_objects}{list of extra files to link with (eg. object
+ files not implied by 'sources', static library that must be explicitly
+ specified, binary resource files, etc.)}{string}
+ \lineiii{extra_compile_args}{any extra platform- and compiler-specific
+ information to use when compiling the source files in 'sources'. For
+ platforms and compilers where "command line" makes sense, this is
+ typically a list of command-line arguments, but for other platforms it
+ could be anything.}{string}
+ \lineiii{extra_link_args}{any extra platform- and compiler-specific
+ information to use when linking object files together to create the
+ extension (or to create a new static Python interpreter). Similar
+ interpretation as for 'extra_compile_args'.}{string}
+ \lineiii{export_symbols}{list of symbols to be exported from a shared
+ extension. Not used on all platforms, and not generally necessary for
+ Python extensions, which typically export exactly one symbol: \code{init} +
+ extension_name. }{string}
+ \lineiii{depends}{list of files that the extension depends on }{string}
+ \lineiii{language}{extension language (i.e. \code{"c"}, \code{"c++"},
+ \code{"objc"}). Will be detected from the source extensions if not provided.
+ }{string}
+ \end{tableiii}
+ \end{classdesc*}
+
+ \begin{classdesc*}{Distribution}
+ A \class{Distribution} describes how to build, install and package up a
+ Python software package.
+
+ See the \function{setup()} function for a list of keyword arguments accepted
+ by the Distribution constructor. \function{setup()} creates a Distribution
+ instance.
+ \end{classdesc*}
+
+ \begin{classdesc*}{Command}
+ A \class{Command} class (or rather, an instance of one of it's subclasses)
+ implement a single distutils command.
+ \end{classdesc*}
+
\section{The low-level interface}
***************
*** 840,846 ****
! \subsubsection{\module{distutils.log} -- Simple PEP282-style logging}
\declaremodule{standard}{distutils.log}
! \modulesynopsis{A simple logging mechanism, PEP282-style}
\warning{Should be replaced with standard \refmodule{logging} module.}
--- 929,935 ----
! \subsubsection{\module{distutils.log} -- Simple \pep{282}-style logging}
\declaremodule{standard}{distutils.log}
! \modulesynopsis{A simple logging mechanism, \pep{282}-style}
\warning{Should be replaced with standard \refmodule{logging} module.}
***************
*** 1009,1012 ****
--- 1098,1104 ----
\declaremodule{standard}{distutils.command.register}
\modulesynopsis{Register a module with the Python Package Index}
+
+ The \code{register} command registers the package with the Python Package Index.
+ This is described more in \pep{301}.
\subsubsection{Creating a new Distutils command}