This allows additional commands to be provided for existing setup.py

scripts without modifying either the distutils installation or the
setup.py scripts of packages with which the new commands will be used.

Specifically, an option is added to distutils that allows additional
packages to be searched for command implementations in addition to
distutils.command.  The additional packages can be specified on the
command line or via the installation or personal configuration files
already loaded by distutils.

For discussion, see the thread starting with:

http://mail.python.org/pipermail/distutils-sig/2004-August/004112.html

This closes SF patch #102241.

1 files changed, 31 insertions, 0 deletions

diff --git a/Doc/dist/dist.tex b/Doc/dist/dist.tex
index 5a95d78..784c908 100644
--- a/Doc/dist/dist.tex
+++ b/Doc/dist/dist.tex
@@ -1946,6 +1946,37 @@ 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.
 
+Beginning with Python 2.4, a third option is available, intended to
+allow new commands to be added which can support existing
+\file{setup.py} scripts without requiring modifications to the Python
+installation.  This is expected to allow third-party extensions to
+provide support for additional packaging systems, but the commands can
+be used for anything distutils commands can be used for.  A new
+configuration option, \option{command\_packages} (command-line option
+\longprogramopt{command-packages}), can be used to specify additional
+packages to be searched for modules implementing commands.  Like all
+distutils options, this can be specified on the command line or in a
+configuration file.  This option can only be set in the
+\code{[global]} section of a configuration file, or before any
+commands on the command line.  If set in a configuration file, it can
+be overridden from the command line; setting it to an empty string on
+the command line causes the default to be used.  This should never be
+set in a configuration file provided with a package.
+
+This new option can be used to add any number of packages to the list
+of packages searched for command implementations; multiple package
+names should be separated by commas.  When not specified, the search
+is only performed in the \module{distutils.command} package.  When
+\file{setup.py} is run with the option
+\longprogramopt{command-packages} \programopt{distcmds,buildcmds},
+however, the packages \module{distutils.command}, \module{distcmds},
+and \module{buildcmds} will be searched in that order.  New commands
+are expected to be implemented in modules of the same name as the
+command by classes sharing the same name.  Given the example command
+line option above, the command \command{bdist\_openpkg} could be
+implemented by the class \class{distcmds.bdist_openpkg.bdist_openpkg}
+or \class{buildcmds.bdist_openpkg.bdist_openpkg}.
+
 
 \chapter{Command Reference}
 \label{reference}