[Python-checkins] devguide: Issue 7997: Explain how to regenerate configure using Autoconf.

[ross.lagerwall]

http://hg.python.org/devguide/rev/5432be4d4e1a
changeset:   494:5432be4d4e1a
user:        Ross Lagerwall <rosslagerwall at gmail.com>
date:        Sun Mar 11 19:22:40 2012 +0200
summary:
  Issue 7997: Explain how to regenerate configure using Autoconf.

Based on info written by David Malcolm.

files:
  committing.rst |   2 +
  patch.rst      |  56 ++++++++++++++++++++++++++++++++++++++
  2 files changed, 58 insertions(+), 0 deletions(-)


diff --git a/committing.rst b/committing.rst
--- a/committing.rst
+++ b/committing.rst
@@ -32,6 +32,8 @@
 * Has the test suite been updated?
 * Has ``Misc/NEWS`` been updated?
 * Has ``Misc/ACKS`` been updated?
+* Has ``configure`` been regenerated, if necessary?
+* Has ``pyconfig.h.in`` been regenerated, if necessary?
 * Has the test suite been run?
 
 Note that the automated patch check can't actually *answer* all of these
diff --git a/patch.rst b/patch.rst
--- a/patch.rst
+++ b/patch.rst
@@ -137,6 +137,62 @@
 Also, please make sure your patch is whitespace normalized. ``patchcheck``
 will check this for you.
 
+Autoconf
+''''''''
+
+If a change is made to Python which relies on some POSIX system-specific
+functionality (such as using a new system call), it is necessary to update the
+``configure`` script to test for availability of the functionality.
+
+Python's ``configure`` script is generated from ``configure.in`` using Autoconf.
+Instead of editing ``configure``, edit ``configure.in`` and then run
+``autoreconf`` to regenerate ``configure`` and a number of other files (such as
+``pyconfig.h``.
+
+When submitting a patch with changes made to ``configure.in``, it is preferred
+to leave out the generated files as differences between Autoconf versions
+frequently results in many spurious changes cluttering the patch. Instead,
+remind any potential reviewers on the tracker to run ``autoreconf``.
+
+Note that running ``autoreconf`` is not the same as running ``autoconf``. For
+example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``.
+``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is
+appropriate.
+
+Python's ``configure.in`` script typically requires a specific version of
+Autoconf.  At the moment, this reads: ``version_required(2.65)``
+
+If the system copy of Autoconf does not match this version, you will need to
+install your own copy of Autoconf:
+
+1. Go to http://ftp.gnu.org/gnu/autoconf/ and download the version of Autoconf
+   matching the one in ``configure.in``::
+
+      wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.65.tar.bz2
+
+2. Unpack the tarball::
+
+      tar -jxf autoconf-2.65.tar.bz2 
+
+3. Build the specified version of Autoconf and install it to a writable location
+   (e.g. within your home directory)::
+
+      pushd autoconf-2.65.tar.bz2
+      ./configure --prefix=$HOME/autoconf-2.65
+      make
+      make install
+
+   This installs a copy of the appropriate version of Autoconf into
+   ~/autoconf-2.65.
+
+4. Go back to the Python source and rerun ``autoreconf``, pointing ``PATH`` at
+   the newly installed copy of Autoconf::
+
+      popd
+      PATH=~/autoconf-2.65/bin:$PATH autoreconf
+
+5. Autoconf should now have updated your local copy of ``configure`` to reflect
+   your changes.
 
 Submitting
 ----------

-- 
Repository URL: http://hg.python.org/devguide