Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pypa/auditwheel

Auditing and relabeling cross-distribution Linux wheels.
https://github.com/pypa/auditwheel

Last synced: 12 days ago
JSON representation

Auditing and relabeling cross-distribution Linux wheels.

Awesome Lists containing this project

README 

        
auditwheel

==========



.. image:: https://travis-ci.org/pypa/auditwheel.svg?branch=main

    :target: https://travis-ci.org/pypa/auditwheel

.. image:: https://badge.fury.io/py/auditwheel.svg

    :target: https://pypi.org/project/auditwheel

.. image:: https://pepy.tech/badge/auditwheel/month

    :target: https://pepy.tech/project/auditwheel/month



Auditing and relabeling of `PEP 600 manylinux_x_y

`_, `PEP 513 manylinux1

`_, `PEP 571 manylinux2010

`_ and `PEP 599 manylinux2014

`_ Linux wheels.



Overview

--------



``auditwheel`` is a command line tool to facilitate the creation of Python

`wheel packages `_ for Linux (containing pre-compiled

binary extensions) that are compatible with a wide variety of Linux distributions,

consistent with the `PEP 600 manylinux_x_y

`_, `PEP 513 manylinux1

`_, `PEP 571 manylinux2010

`_ and `PEP 599 manylinux2014

`_ platform tags.



``auditwheel show``: shows external shared libraries that the wheel depends on

(beyond the libraries included in the ``manylinux`` policies), and

checks the extension modules for the use of versioned symbols that exceed

the ``manylinux`` ABI.



``auditwheel repair``: copies these external shared libraries into the wheel itself,

and automatically modifies the appropriate ``RPATH`` entries such that these libraries

will be picked up at runtime. This accomplishes a similar result as if the libraries had

been statically linked without requiring changes to the build system. Packagers are

advised that bundling, like static linking, may implicate copyright concerns.



Requirements

------------

- OS: Linux

- Python: 3.8+

- `patchelf `_: 0.14+



Only systems that use `ELF

`_-based linkage

are supported (this should be essentially every Linux).



In general, building ``manylinux1`` wheels requires running on a CentOS5

machine, building ``manylinux2010`` wheels requires running on a CentOS6

machine, and building ``manylinux2014`` wheels requires running on a CentOS7

machine, so we recommend using the pre-built manylinux `Docker images

`_, e.g. ::



  $ docker run -i -t -v `pwd`:/io quay.io/pypa/manylinux1_x86_64 /bin/bash



Installation

------------



``auditwheel`` can be installed using pip:



.. code:: bash



  $ pip3 install auditwheel



Examples

--------



Inspecting a wheel: ::



    $ auditwheel show cffi-1.5.0-cp35-cp35m-linux_x86_64.whl



    cffi-1.5.0-cp35-cp35m-linux_x86_64.whl is consistent with the

    following platform tag: "linux_x86_64".



    The wheel references the following external versioned symbols in

    system-provided shared libraries: GLIBC_2.3.



    The following external shared libraries are required by the wheel:

    {

        "libc.so.6": "/lib64/libc-2.5.so",

        "libffi.so.5": "/usr/lib64/libffi.so.5.0.6",

        "libpthread.so.0": "/lib64/libpthread-2.5.so"

    }



    In order to achieve the tag platform tag "manylinux1_x86_64" the

    following shared library dependencies will need to be eliminated:



    libffi.so.5



Repairing a wheel. ::



    $ auditwheel repair cffi-1.5.2-cp35-cp35m-linux_x86_64.whl

    Repairing cffi-1.5.2-cp35-cp35m-linux_x86_64.whl

    Grafting: /usr/lib64/libffi.so.5.0.6

    Setting RPATH: _cffi_backend.cpython-35m-x86_64-linux-gnu.so to "$ORIGIN/.libs_cffi_backend"

    Previous filename tags: linux_x86_64

    New filename tags: manylinux1_x86_64

    Previous WHEEL info tags: cp35-cp35m-linux_x86_64

    New WHEEL info tags: cp35-cp35m-manylinux1_x86_64



    Fixed-up wheel written to /wheelhouse/cffi-1.5.2-cp35-cp35m-manylinux1_x86_64.whl



Limitations

-----------



1. ``auditwheel`` uses the `DT_NEEDED `_

   information (like ``ldd``) from the Python extension modules to determine

   which system libraries they depend on. Code that dynamically

   loads libraries at runtime using ``ctypes`` / ``cffi`` (from Python) or

   ``dlopen`` (from C/C++) doesn't contain this information in a way that can

   be statically determined, so dependencies that are loaded via those

   mechanisms will be missed.

2. There's nothing we can do about "fixing" binaries if they were compiled and

   linked against a too-recent version of ``libc`` or ``libstdc++``. These

   libraries (and some others) use symbol versioning for backward

   compatibility. In general, this means that code that was compiled against an

   old version of ``glibc`` will run fine on systems with a newer version of

   ``glibc``, but code what was compiled on a new system won't / might not run

   on older system.



   So, to compile widely-compatible binaries, you're best off doing the build

   on an old Linux distribution, such as a manylinux Docker image.



Testing

-------



The tests can be run with ``nox``, which will automatically install

test dependencies.



Some of the integration tests also require a running and accessible Docker

daemon. These tests will pull a number of docker images if they are not already

available on your system, but it won't update existing images.

To update these images manually, run::



    docker pull python:3.8-slim

    docker pull quay.io/pypa/manylinux1_x86_64

    docker pull quay.io/pypa/manylinux2010_x86_64

    docker pull quay.io/pypa/manylinux2014_x86_64

    docker pull quay.io/pypa/manylinux_2_28_x86_64



You may also remove these images using ``docker rmi``.



Code of Conduct

---------------



Everyone interacting in the ``auditwheel`` project's codebases, issue trackers,

chat rooms, and mailing lists is expected to follow the

`PSF Code of Conduct`_.



.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md