From c7f9f2bfc7dbe9d26d0cbe159e9e8c2a5efe21d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89ric=20Araujo?= <merwok@netwok.org>
Date: Thu, 9 Jun 2011 08:18:17 +0200
Subject: [PATCH] Document how to define extension modules in setup.cfg

---
 Doc/library/packaging.compiler.rst |  6 ++++--
 Doc/packaging/setupcfg.rst         | 32 ++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
index dac62632a4f..cf88685144a 100644
--- a/Doc/library/packaging.compiler.rst
+++ b/Doc/library/packaging.compiler.rst
@@ -569,10 +569,10 @@ extension modules.
 .. class:: Extension
 
    The Extension class describes a single C or C++ extension module.  It accepts
-   the following keyword arguments in its constructor
+   the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
-   | argument name          | value                          | type                      |
+   | argument name          | value                          | type [#]_                 |
    +========================+================================+===========================+
    | *name*                 | the full name of the           | string                    |
    |                        | extension, including any       |                           |
@@ -670,3 +670,5 @@ extension modules.
    |                        | from the source extensions if  |                           |
    |                        | not provided.                  |                           |
    +------------------------+--------------------------------+---------------------------+
+
+.. [#] For values documented as lists, the given type is the type of each element.
diff --git a/Doc/packaging/setupcfg.rst b/Doc/packaging/setupcfg.rst
index b657d14feeb..aa8216fdf1e 100644
--- a/Doc/packaging/setupcfg.rst
+++ b/Doc/packaging/setupcfg.rst
@@ -141,6 +141,9 @@ files
    Modules, scripts, data, documentation and other files to include in the
    distribution.
 
+extension sections
+   Options used to build extension modules.
+
 command sections
    Options given for specific commands, identical to those that can be given
    on the command line.
@@ -736,6 +739,35 @@ We use brace expansion syntax to place all the shell and batch scripts into
 {scripts} category.
 
 
+Extension sections
+------------------
+
+If a project includes extension modules written in C or C++, each one of them
+needs to have its options defined in a dedicated section.  Here's an example::
+
+   [files]
+   packages = coconut
+
+   [extension=_fastcoconut]
+   name = coconut._fastcoconut
+   language = cxx
+   sources = cxx_src/cononut_utils.cxx
+             cxx_src/python_module.cxx
+   include_dirs = /usr/include/gecode
+                  /usr/include/blitz
+   extra_compile_args =
+       -fPIC -O2
+       -DGECODE_VERSION=$(./gecode_version) -- sys.platform != 'win32'
+       /DGECODE_VERSION='win32' -- sys.platform == 'win32'
+
+The section name must start with ``extension=``; the righ-hand part is currently
+discarded.  Valid fields and their values are listed in the documentation of the
+:class:`packaging.compiler.extension.Extension` class; values documented as
+Python lists translate to multi-line values in the configuration file.  In
+addition, multi-line values accept environment markers on each line, after a
+``--``.
+
+
 Command sections
 ----------------