[Python-checkins] python/dist/src/Doc/dist dist.tex,1.78,1.79

[fdrake at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/dist
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9863

Modified Files:
	dist.tex 
Log Message:
start filling in documentation on extending distutils


Index: dist.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/dist/dist.tex,v
retrieving revision 1.78
retrieving revision 1.79
diff -C2 -d -r1.78 -r1.79
*** dist.tex	18 Jun 2004 17:31:23 -0000	1.78
--- dist.tex	2 Aug 2004 21:39:11 -0000	1.79
***************
*** 1888,1893 ****
  
  
! %\chapter{Extending the Distutils}
! %\label{extending}
  
  
--- 1888,1911 ----
  
  
! \chapter{Extending Distutils \label{extending}}
! 
! Distutils can be extended in various ways.  Most extensions take the
! form of new commands or replacements for existing commands.  New
! commands may be written to support new types of platform-specific
! packaging, for example, while replacements for existing commands may
! be made to modify details of how the command operates on a package.
! 
! Most extensions of the distutils are made within \file{setup.py}
! scripts that want to modify existing commands; many simply add a few
! file extensions that should be copied into packages in addition to
! \file{.py} files as a convenience.
! 
! Most distutils command implementations are subclasses of the
! \class{Command} class from \refmodule{distutils.cmd}.  New commands
! may directly inherit from \class{Command}, while replacements often
! derive from \class{Command} indirectly, directly subclassing the
! command they are replacing.  Commands are not required to derive from
! \class{Command}, but must implement the interface documented as part
! of that class.
  
  
***************
*** 1901,1904 ****
--- 1919,1950 ----
  %\XXX{Would an uninstall command be a good example here?}
  
+ \section{Integrating new commands}
+ 
+ There are different ways to integrate new command implementations into
+ distutils.  The most difficult is to lobby for the inclusion of the
+ new features in distutils itself, and wait for (and require) a version
+ of Python that provides that support.  This is really hard for many
+ reasons.
+ 
+ The most common, and possibly the most reasonable for most needs, is
+ to include the new implementations with your \file{setup.py} script,
+ and cause the \function{distutils.core.setup()} function use them:
+ 
+ \begin{verbatim}
+ from distutils.command.build_py import build_py as _build_py
+ from distutils.core import setup
+ 
+ class build_py(_build_py):
+     """Specialized Python source builder."""
+ 
+     # implement whatever needs to be different...
+ 
+ setup(cmdclass={'build_py': build_py},
+       ...)
+ \end{verbatim}
+ 
+ This approach is most valuable if the new implementations must be used
+ to use a particular package, as everyone interested in the package
+ will need to have the new command implementation.