moonbuggy2000/python-musl-wheels

Python musl wheel 镜像

在Docker容器中构建的Python musl wheel，用于导入多阶段构建。

• 基本原理
• Wheel类型
• 使用方法
  • 使用Docker镜像
    • 多阶段构建示例
• 构建wheel镜像
  • 默认构建
  • 构建环境
  • 构建示例
  • 添加新wheel
• 链接

基本原理

许多Python模块目前没有预构建的musl wheel，特别是对于非x64架构。这会导致Docker中的Python构建缓慢，因为当镜像构建时，没有可用wheel的模块需要从源代码构建。

本项目生成的Docker镜像包含wheel文件，镜像标签指定了模块和Python版本（旧镜像标签中还包含架构）。这些镜像旨在用作Docker多阶段构建的一部分，为Python阶段提供预构建的wheel。镜像包含标签中指定的模块及其所有依赖的wheel。

[!NOTE] 这些镜像主要用于我自己的Docker镜像，避免每次对Python镜像进行缓存破坏更改时都需要编译模块。此仓库不会是全面的wheel集合。

Wheel类型

提供两种不同类型的wheel：

• 包含共享库的wheel

  这些wheel由https://github.com/pypa/auditwheel%E5%A4%84%E7%90%86%EF%BC%8C%E5%BA%94%E7%AC%A6%E5%90%88%E7%9B%B8%E5%85%B3PEP 656规范，具有最高的可移植性。

  包含这些wheel的Docker镜像推送到https://hub.docker.com/r/moonbuggy2000/python-musl-wheels%EF%BC%8Cwheel%E6%96%87%E4%BB%B6%E5%90%8D%E4%B8%AD%E5%8C%85%E5%90%AB%60-musllinux%60%E3%80%82

• 不包含共享库的wheel

  这些wheel通过依赖系统库而非捆绑可能重复的共享库，生成更小的最终Docker镜像。但需要系统库存在且与wheel构建时依赖的库兼容，因此可移植性较低。

  包含这些wheel的Docker镜像推送到https://hub.docker.com/r/moonbuggy2000/python-alpine-wheels%EF%BC%8Cwheel%E6%96%87%E4%BB%B6%E5%90%8D%E4%B8%AD%E5%8C%85%E5%90%AB%60-linux%60%E3%80%82

当前wheel镜像基于Alpine 3.19和musl 1.2构建，部分musl 1.1的wheel可在wheels/目录中找到。

[!NOTE] 若PyPi上已有某架构的预构建wheel，“不包含共享库”的镜像可能会使用这些wheel而非自行构建。因此，特别是对于amd64和arm64架构，部分“python-alpine-wheels”镜像中的wheel可能实际包含共享库。

本仓库的目的是填补PyPi预构建wheel在更多架构上的空白。构建不需要的wheel会扩大这一差距，且不包含共享库节省的磁盘空间有限，难以证明构建时间的合理性。

使用方法

本仓库的wheels/目录中包含可直接使用的wheel文件。此外，Docker镜像可作为其他镜像构建过程的一部分拉取使用。

对于使用SSL库的模块，wheels/目录中的wheel文件默认应为OpenSSL构建版本。LibreSSL构建版本通常可通过Docker镜像获取。

使用Docker镜像

较新的构建仅为每个wheel推送单个多平台标签，格式如下：

moonbuggy2000/python-musl-wheels:<module><module_version>-py<python_version>

示例：

moonbuggy2000/python-musl-wheels:cryptography45.0.1-py3.8

旧版本构建为每个架构推送独立镜像，格式如下：

moonbuggy2000/python-musl-wheels:<module><module_version>-py<python_version>-<arch>

示例：

moonbuggy2000/python-musl-wheels:cryptography3.4.8-py3.8-armv7

多阶段构建示例

dockerfile
ARG PYTHON_VERSION="3.8"

# 从多平台镜像获取cryptography模块
FROM --platform="${TARGETPLATFORM}" \
  "moonbuggy2000/python-musl-wheels:cryptography45.0.1-py${PYTHON_VERSION}" \
  AS mod_cryptography

# 或从旧版单架构镜像获取
FROM "moonbuggy2000/python-musl-wheels:cryptography3.4.8-py${PYTHON_VERSION}-armv7" \
  AS mod_cryptography

# 获取其他模块
FROM --platform="${TARGETPLATFORM}" \
  "moonbuggy2000/python-musl-wheels:some-other-module1.0.0-py${PYTHON_VERSION}" \
  AS mod_some_other

# 构建Python应用镜像
FROM "arm32v7/python:${PYTHON_VERSION}"

WORKDIR "/wheels"

COPY --from=mod_cryptography / ./
COPY --from=mod_some_other / ./

WORKDIR "/app"

# .. 设置虚拟环境等 ..

RUN python3 -m pip install /wheels/*
# 或
RUN python3 -m pip install --find-links /wheels/ cryptography some_other_module

# .. 其他步骤 ..

构建wheel镜像

sh
./build.sh <module><module_version>-py<python_version>-<arch>

除./build.sh <module>外，其他参数均为可选。<module>可包含-openssl或-libressl后缀（如适用）。

目前，-libressl构建不支持s390x架构，因为Alpine包仓库中没有libressl-dev。

若未提供<module_version>，将构建PyPi上的最新版本。若省略<python_version>，将使用Docker Hubhttps://hub.docker.com/_/python的最新版本。若未指定<arch>，将构建所有可能的架构。

要为所有默认Python版本（在_build.sh_中定义）构建模块，可使用pyall作为py<python_version>。

可通过向_build.sh_传递多个参数一次构建多个模块。

默认构建

_build.sh_中内置了一些默认模块和Python版本，可通过特殊构建参数使用：

• all - 为所有默认Python版本构建所有默认模块
• core - 为所有默认Python版本构建核心默认模块（适用于其他模块常用的依赖，确保在all构建时可用）
• check - 检查PyPi上是否有默认模块的新版本，然后退出不开始构建
• update - 与check类似，但继续为所有默认Python版本构建新版本

这些构建应作为_build.sh_的唯一参数独立执行。它们将构建包含和不包含共享库的两种wheel。

远程仓库的数据在本地缓存24小时，因此check的输出在构建和推送模块后不会立即变化。必要时可使用CLEAN_CACHE（见下文）清除缓存。

构建环境

构建脚本使用环境变量确定某些行为，特别是与Docker Hub推拉相关的操作。

最常用的环境变量如下：

这些变量的命名目前不够清晰一致，未来可能会调整。

默认行为是构建包含共享库的wheel，将wheel输出到主机的wheels/目录，且不推送任何镜像到Docker Hub。

构建示例

sh
# 最新cryptography，OpenSSL，最新Python，所有架构
./build.sh cryptography
# 或
./build.sh cryptography-openssl

# 最新cryptography，LibreSSL，最新Python，amd64架构
# 推送到Docker仓库
DO_PUSH=1 ./build.sh cryptography-libreSSL-amd64

# cryptography 36.0.1，OpenSSL，所有默认Python版本，amd64架构
# 不捆绑共享库
NO_SHARED=1 ./build.sh cryptography-openssl36.0.1-pyall-amd64

# 同时构建多个模块
./build.sh cryptography-openssl-py3.9 cffi1.15.1-armv7 pycparser toml-pyall

# 所有默认模块，所有默认Python版本，所有架构
# 从源码构建，同时构建两种类型的wheel
# 并推送到Docker仓库
DO_PUSH=1 ./build.sh all

添加新wheel

构建系统通常能够使用适当格式的镜像标签构建任何请求的wheel。

默认情况下，wheel在Docker容器中通过以下命令构建：python3 -m pip wheel -w "${WHEELS_DIR}" "${MODULE_NAME}==${MODULE_VERSION}"

scripts/<module_name>.sh

特定wheel所需的默认构建设置之外的任何配置，可通过可选的scripts/<module_name>.sh文件（与镜像标签中的<module_name>匹配）处理。这是安装Python/pip不会安装的构建依赖（如通过apk、make或wget）的适当位置。

若存在此文件，mod_build函数将在Dockerfile中的pip wheel命令之前立即调用。

可通过在scripts/<module_name>.sh文件中放置自定义命令并设置WHEEL_BUILT_IN_SCRIPT来覆盖Dockerfile中的pip wheel命令，以防止执行默认命令。

mod_depends函数在检出后由构建系统调用，从本仓库获取任何所需模块（若未找到则回退到PyPi），这些依赖将在Dockerfile开始构建模块前安装。

示例可参见scripts/paramiko.sh。

链接

GitHub: https://github.com/moonbuggy/docker-python-musl-wheels

Docker Hub:

• https://hub.docker.com/r/moonbuggy2000/python-alpine-wheels
• https://hub.docker.com/r/moonbuggy2000/python-musl-wheels

相关项目:

• https://github.com/moonbuggy/python-dependency-groups