102 - Wheel 包构建脚本 build.sh.md · src-whl/docs

# Wheel 包构建脚本 build.sh

## 1. 概述

Wheel 包源码仓库中 build.sh 是组件中的核心文件，通过执行 build.sh 就能得到构建测试后的 .whl 文件。

构建脚本 build.sh 遵循以下原则。

1. 构建过程中不能使用不可信内容
2. 构建框架提供通用构建命令，少数软件包需要重写构建过程
3. Wheel 源码包可能在不同架构上构建命令不同，按架构拆分为 build-x86\_64.sh、build-aarch64.sh
4. 同一脚本支持多 Python 版本构建、多环境构建
5. 所有构建将在 manylinux 容器中运行

## 2. build.sh 示例详解

build.sh 为 Wheel 软件包的构建脚本，将会在 manylinux 容器中运行，最后得到构建好的 .whl 包。构建框架中提供了一系列构建通用命令，通用命令无法覆盖，则可以通过参数定制、重构编译命令的方式定制构建过程。

默认的 build.sh 模版如下。

```shell
#!/bin/bash
set -euo pipefail

# 导入通用函数
git clone https://gitee.com/src-anolis-whl/build-common
. build-common/common.sh

# =======构建前准备，可以安装一些构建依赖等==========
setup_py39 # for Python 3.9, default
#setup_py38 # for Python 3.8
#setup_py312 # for Python 3.12
## 其他系统依赖
#yum install -y
# ===================================================

prepare_source
apply_patches

# 对于每个Python版本，构建相应的whl
for pybin in "${PYTHON_BINS[@]}"; do
    get_build_env $pybin

# 构建Python环境准备
    #$PIPBIN install -i https://pypi.openanolis.cn/prod/simple

# ==========构建环境变量==========
    export BUILD_WHEEL_FLAGS=
    #export CUDA_C_FLAGS=
    # ================================
    build_wheel $pybin

# 测试Python环境准备
    #$PIPBIN install

# ==========测试环境变量==========
    export PYTEST_FLAGS=
    export SETUPPYTEST_FLAGS=
    # ================================
    build_test $pybin
done

# 调用auditwheel将运行依赖捆绑至whl中
# 使用 --exclude xxx.so 来跳过加入某些动态链接库
bundle_libs

# 构建产物收集
output_whls
```

build.sh 中的步骤以及对应的框架命令如下表。其中部分步骤需要自定义，构建步骤以及测试步骤可以根据不同的 Wheel 包进行重写。

特别注意，进行测试步骤前，不要下载不可信内容（例如从上游安装 Python 依赖等）。

| 步骤             | 对应命令                   | 命令作用                                        | 可自定义内容                                                                       | 备注                                               |
| ---------------- | -------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------- |
| 设置 Python 环境 | `setup_py310`<br>`setup_py38` | 设置 Python 版本                                | N/A                                                                                |                                                    |
| 准备环境         | 自定义                     | N/A                                             | 安装 RPM 依赖；<br>编译安装开源软件                                                |                                                    |
| 准备源码         | `prepare_source`           | 解压源码压缩包                                  | N/A                                                                                |                                                    |
| 合入补丁         | `apply_patches`            | 按照字典序（0001、0002、1001、…）为源码合入补丁 | N/A                                                                                |                                                    |
| 安装构建依赖     | 自定义                     | N/A                                             | 安装 Wheel 构建依赖                                                                | 仅限现有申威仓库和中央仓库 |
| 获取构建环境变量 | `get_build_env`            | 设置构建运行时变量                              | N/A                                                                                |                                                    |
| 设置构建变量     | 自定义                     | N/A                                             | 设置 `BUILD_WHEEL_FLAGS` 为 pip wheel 提供额外参数；<br>其他构建环境变量           |                                                    |
| 构建             | `build_wheel`              | 执行 pip wheel 进行构建                         | N/A                                                                                |                                                    |
| 安装测试依赖     | 自定义                     | N/A                                             | 安装测试依赖                                                                       | 不限安装来源                                       |
| 设置测试环境变量 | 自定义                     | N/A                                             | pytest 的额外参数 `PYTEST_FLAGS`；<br>setup.py test 的额外参数 `SETUPPYTEST_FLAGS` |                                                    |
| 测试             | `build_test`               | 执行测试                                        | N/A                                                                                | 非设备、环境问题不可跳过                           |
| 打包运行库       | `bundle_libs`              | 使用 auditwheel 将系统二进制库打包进 .whl 文件  | 传入`--exclude`参数忽略动态链接库                                                  |                                                    |
| 收集产物         | `output_whls`              | 收集 .whl 文件至源码目录                        | N/A                                                                                |                                                    |

## 3. 多 Python 构建

大部分 Wheel 包是通用 Python 包，兼容所有 Python 3 版本（甚至 Python 2）。但仍有部分包需要使用对应版本 Python 环境进行构建。对于这部分包，框架中提供了不同 Python 环境来构建。

目前框架支持多种 Python 环境：Python 3.8、Python 3.10、Python 3.12。提供了对应的设置函数。

* `setup_py38`
* `setup_py310`
* `setup_py312`

设置完毕后，会自动向 PYTHON\_BINS 变量中添加对应的二进制目录，`get_build_env`会获取当前环境配置，将当前环境 Python、PIP 二进制路径赋值 PYTHONBIN、PIPBIN 环境变量。

## 4. 多环境构建

对于涉及 CUDA 构建的 Wheel 包，框架中提供了对应的环境来辅助构建。在多环境构建中，可以按需执行「创建环境」、「构建」、「销毁环境」等操作。

![多环境构建](./assets/multi-python-ver-build.png)

目前框架中支持三种运行环境：CPU、CUDA 11.8、CUDA 12.1。对于 CUDA 环境，框架中提供了创建和销毁的函数，同时在环境声明周期中，设置了对应的环境变量 CMAKE\_CUDA\_COMPILER、CMAKE\_CUDA\_ARCH\_LIST、USE\_CUDA、CUDA\_VER。

* `prepare_cu118_env`：创建 CUDA 11.8 开发环境，并设置环境变量
* `destroy_cu118_env`：销毁 CUDA 11.8 的环境
* `prepare_cu121_env`：创建 CUDA 12.1 开发环境，并设置环境变量
* `destroy_cu121_env`：销毁 CUDA 12.1 的环境

对于多环境构建，需要修改 Wheel 包的版本号，约定在版本号后加上 `+cpu` 或者 `+cu<cuda_version>`，例如「faiss-1.8.0+cpu」、「faiss-1.8.0+cu121」。部分包可以通过构建参数指定版本号后缀，例如 PyTorch。对于固定版本号的包，需要在构建时修改源码，例如 Faiss。

## 5. 附录：构建阶段环境变量

| 变量名                  | 说明                   | 生命周期                                                  |
| ----------------------- | ---------------------- | --------------------------------------------------------- |
| PYTHON\_BINS            | Python、PIP 二进制目录 | 构建脚本生命周期内，不可修改                              |
| PYTHONBIN               | Python 二进制路径      | `get_build_env` 执行后，不可修改                          |
| PIPBIN                  | PIP 二进制路径         |                                                           |
| PYTHON\_VERSION         | 当前 Python 版本号     |                                                           |
| BUILD\_WHEEL\_FLAGS     | 额外构建参数           | 构建阶段，可修改                                          |
| SETUPPYTEST\_FLAGS      | setup.py 测试额外参数  | 测试阶段，可修改                                          |
| PYTEST\_FLAGS           | PyTest 测试额外参数    |                                                           |
| CMAKE\_CUDA\_COMPILER   | CMake CUDA 参数        | `prepare_cuxxx_env` 与 `destroy_cuxxx_env` 之间，不可修改 |
| CMAKE\_CUDA\_ARCH\_LIST | CMake CUDA 参数        |                                                           |
| USE\_CUDA               | CUDA 构建              |                                                           |
| CUDA\_VER               | CUDA 版本              |                                                           |

src-whl/docs

About

Releases

Contributors

Activities