build: make extensions an array and advertise variants

This will allow distributions to contain multiple implementations of
the same extension. This will be useful for distributing e.g.
readline versus libedit, static versus dynamic linking, etc.

Author: indygreg

README.rst

@@ -319,14 +319,20 @@ core
       An array of linking requirement maps. (See below for data format.)
 
 extensions
-   A map of extension names to a map describing the extension.
+   A map of extension names to an array of maps describing candidate extensions.
 
    Extensions are non-core/non-essential parts of the Python distribution that
    are frequently built as standalone entities.
 
    Names in this map denote the name of the extension module.
 
-   Values are maps with the following keys:
+   Values are arrays of maps. Each map represents a potential candidate
+   providing the extension. There is frequently only a single extension
+   candidate. Multiple candidates can occur if there are e.g. varying
+   libraries an extension can be linked against to supply underlying
+   functionality.
+
+   Each map has the following keys:
 
    in_core
       Boolean indicating if this extension is defined by the core distribution.
@@ -359,6 +365,11 @@ extensions
       The path to a static library defining this extension module. May not
       be defined.
 
+   variant
+      String describing this extension variant. Downstream consumers can key off
+      this value to choose an appropriate extension variant when there are
+      multiple options.
+
 Each entry in a ``links`` array is a map with the following keys:
 
 name

cpython-linux/build.py

@@ -481,12 +481,13 @@ def process_setup_line(line):
                     'system': True,
                 })
 
-        bi['extensions'][extension] = {
+        bi['extensions'][extension] = [{
             'in_core': False,
             'init_fn': 'PyInit_%s' % extension,
             'links': links,
             'objs': objs,
-        }
+            'variant': 'default',
+        }]
 
 
     found_start = False
@@ -516,12 +517,13 @@ def process_setup_line(line):
     # can register their PyInit_ functions.
     for name, init_fn in sorted(config_c_in.items()):
         log('adding in-core extension %s' % name)
-        bi['extensions'][name] = {
+        bi['extensions'][name] = [{
             'in_core': True,
             'init_fn': init_fn,
             'links': [],
             'objs': [],
-        }
+            'variant': 'default',
+        }]
 
     # Any paths left in modules_objs are not part of any extension and are
     # instead part of the core distribution.

cpython-macos/build.py

@@ -237,12 +237,13 @@ def process_setup_line(line):
                     'system': True,
                 })
 
-        bi['extensions'][extension] = {
+        bi['extensions'][extension] = [{
             'in_core': False,
             'init_fn': 'PyInit_%s' % extension,
             'links': links,
             'objs': objs,
-        }
+            'variant': 'default',
+        }]
 
     found_start = False
 
@@ -267,12 +268,13 @@ def process_setup_line(line):
 
     for name, init_fn in sorted(config_c_in.items()):
         log('adding in-core extension %s' % name)
-        bi['extensions'][name] = {
+        bi['extensions'][name] = [{
             'in_core': True,
             'init_fn': init_fn,
             'links': [],
             'objs': [],
-        }
+            'variant': 'default',
+        }]
 
     # Any paths left in modules_objs are not part of any extensions and
     # are instead part of the core distribution.

cpython-windows/build.py

@@ -1170,13 +1170,14 @@ def find_additional_dependencies(project: pathlib.Path):
         additional_depends = find_additional_dependencies(ext)
         additional_depends -= CONVERT_TO_BUILTIN_EXTENSIONS.get(ext, {}).get('ignore_additional_depends', set())
 
-        res['extensions'][ext] = {
+        res['extensions'][ext] = [{
             'in_core': False,
             'objs': [],
             'init_fn': 'PyInit_%s' % ext,
             'static_lib': None,
             'links': [{'name': n[:-4], 'system': True} for n in sorted(additional_depends)],
-        }
+            'variant': 'default',
+        }]
 
         for obj in process_project(ext, dest_dir):
             res['extensions'][ext]['objs'].append('build/extensions/%s/%s' % (ext, obj))
@@ -1196,7 +1197,7 @@ def find_additional_dependencies(project: pathlib.Path):
         # Copy the extension static library.
         ext_static = outputs_path / ('%s.lib' % ext)
         dest = dest_dir / ('%s.lib' % ext)
-        res['extensions'][ext]['static_lib'] = 'build/extensions/%s/%s.lib' % (ext, ext)
+        res['extensions'][ext][0]['static_lib'] = 'build/extensions/%s/%s.lib' % (ext, ext)
         log('copying static extension %s' % ext_static)
         shutil.copyfile(ext_static, dest)