[Distutils] Working toward Linux wheel support

Nick Coghlan ncoghlan at gmail.com
Fri Jul 17 10:22:27 CEST 2015

On 17 July 2015 at 03:41, Nate Coraor <nate at bx.psu.edu> wrote:
> Hi all,
> I've recently been working on adding SOABI support for Python 2.x and other
> pieces needed to get wheels w/ C extensions for Linux working. Here's the
> work for wheels:
>     https://bitbucket.org/pypa/wheel/pull-request/54/
> Based on that, I've added support for those wheels to pip here:
>     https://github.com/natefoo/pip/tree/linux-wheels
> As mentioned in the wheels PR, there are some questions and decisions made
> that I need guidance on:
> - On Linux, the distro name/version (as determined by
> platform.linux_distribution()) will be appended to the platform string, e.g.
> linux_x86_64_ubuntu_14_04. This is going to be necessary to make a
> reasonable attempt at wheel compatibility in PyPI. But this may violate PEP
> 425.

I think it's going beyond it in a useful way, though. At the moment,
the "linux_x86_64" platform tag *under*specifies the platform - a
binary extension built on Ubuntu 14.04 with default settings may not
work on CentOS 7, for example.

Adding in the precise distro name and version number changes that to
*over*specification, but I now think we can address that through
configuration settings on the installer side that allow the
specification of "compatible platforms". That way a derived
distribution could add the corresponding upstream distribution's
platform tag and their users would be able to install the relevant
wheel files by default.

Rather than putting the Linux specific platform tag derivation logic
directly in the tools, though, what if we claimed a file under the
"/etc/python" subtree and used it to tell the tools what platform tags
to use? For example, we could put the settings relating to package
tags into "/etc/python/binary-compatibility.cfg" and allow that to be
overridden on a per-virtualenv basis with a binary-compatibility.cfg
file within the virtualenv.

For example, we could have a section where for a given platform, we
overrode both the build and install tags appropriately. For RHEL 7.1,
that may look like:


Using JSON rather than an ini-style format would also work:

      "linux_x86_64": {
        "build": "rhel_7_1",
        "install": ["rhel_7_0", "rhel_7_1", "centos_7_1406", "centos_7_1503"]

The reason I like this approach is that it leaves the definition of
ABI compatibility in the hands of the distros, but also makes it safe
to publish Linux wheel files on PyPI (just not with the generic
linux_x86_64 platform tag).

> - By default, wheels will be built using the most specific platform
> information. In practice, I build our wheels[1] using Debian Squeeze in
> Docker and therefore they should work on most currently "supported" Linuxes,
> but allowing such wheels to PyPI could still be dangerous because forward
> compatibility is not always guaranteed (e.g. if a SO version/name changes,
> or a C lib API method changes in a non-backward compatible way but the SO
> version/name does not change). That said, I'd be happy to make a much more
> generalized version of our docker-build[2] system that'd allow package
> authors to easily/rapidly build distro/version-specific wheels for many of
> the popular Linux distros. We can assume that a wheel built on a vanilla
> install of e.g. Ubuntu 14.04 will work on any other installation of 14.04
> (this is what the distro vendors promise, anyway).

Right, if we break ABI within a release, that's our fault (putting on
my distro developer hat), and folks will rightly yell at us for it. I
was previously wary of this approach due to the "what about derived
distributions?" problem, but realised recently that a config file that
explicitly lists known binary compatible platforms should suffice for
that. There's only a handful of systems folks are likely want to
prebuild wheels for (Debian, Ubuntu, Fedora, CentOS/RHEL, openSuse),
and a configuration file based system allows ABI compatible derived
distros to be handled as if they were their parent.

> - I attempt to set the SOABI if the SOABI config var is unset, this is for
> Python 2, but will also be done even on Python 3. Maybe that is the wrong
> decision (or maybe SOABI is guaranteed to be set on Python 3).

Python 3 should always set it, but if it's not present for some
reason, deriving it makes sense.

> - Do any other implementations define SOABI? PyPy does not, I did not test
> others. What should we do with these?

The implementation identifier is also included in the compatibility
tags, so setting that in addition to the platform ABI tag when a wheel
contains binary extensions should suffice.

> Because the project I work for[3] relies heavily on large number of
> packages, some of which have complicated build-time dependencies, we have
> always provided them as eggs and monkeypatched platform support back in to
> pkg_resources. Now that the PyPA has settled on wheels as the preferred
> binary packaging format, I am pretty heavily motivated to do the work to
> work out all the issues with this implementation.

Thank you!


Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Distutils-SIG mailing list