konstin2/maturin

Maturin Docker镜像文档

镜像概述

本镜像基于manylinux2010构建，预装maturin工具，旨在简化Python原生扩展包的构建流程。maturin（前身为pyo3-pack）是一款零配置工具，可替代setuptools-rust和milksnake，用于将带有pyo3、rust-cpython、cffi绑定的Rust crate或Rust二进制文件构建为Python包，并支持发布到PyPI。该镜像确保构建的Linux原生模块符合manylinux标准，具备广泛的系统兼容性。

核心功能与特性

• manylinux兼容性：基于官方manylinux2010镜像构建，确保生成的wheels符合manylinux标准，可在大多数Linux系统上运行。
• 工具预装：内置maturin，无需额外安装即可直接使用其核心功能。
• 多绑定支持：自动检测pyo3和rust-cpython绑定，通过参数指定cffi或***（二进制）绑定。
• 跨Python版本：支持为Python 3.5+构建wheels，自动发现系统中的Python解释器。
• 多平台支持：可在Linux、Windows、Mac和FreeBSD上使用（镜像本身为Linux平台）。
• 零配置集成：无需额外配置文件，可与现有setuptools-rust或milksnake配置共存，支持tox等测试工具集成。

使用场景

• 开发跨平台Python原生扩展包，需确保Linux兼容性。
• 构建符合manylinux标准的wheels并发布到PyPI。
• 在CI/CD流程中自动化构建Rust编写的Python扩展。
• 开发混合Rust/Python项目，需将Rust代码作为Python模块集成。

使用方法与配置说明

基本使用

通过Docker运行镜像，挂载项目目录并执行maturin命令：

bash
docker run --rm -v $(pwd):/io docker.xuanyuan.run/konstin2/maturin build

主要命令

maturin提供三个核心命令：

1. maturin publish
   构建Python包并发布到PyPI。

   bash
   docker run --rm -v $(pwd):/io docker.xuanyuan.run/konstin2/maturin publish -u <username> -p <password>
   

2. maturin build
   构建wheels并存储在target/wheels目录（默认），不自动上传。可配合twine手动上传。

   bash
   docker run --rm -v $(pwd):/io docker.xuanyuan.run/konstin2/maturin build --release -o /io/target/wheels
   

3. maturin develop
   构建crate并直接安装到当前虚拟环境（需挂载虚拟环境目录）。

   bash
   docker run --rm -v $(pwd):/io -v /path/to/venv:/venv docker.xuanyuan.run/konstin2/maturin develop --release
   

配置参数

通用参数

publish命令特有参数

项目配置

通过Cargo.toml配置Python元数据

在Cargo.toml中添加[package.metadata.maturin] section配置Python包信息：

toml
[package.metadata.maturin]
requires-dist = ["flask~=1.1.0", "toml==0.10.0"]  # 依赖项，相当于install_requires
classifier = ["Programming Language :: Python"]  # Trove分类器
requires-python = ">=3.5"  # Python版本要求

[package.metadata.maturin.scripts]
get_42 = "my_project:DummyClass.get_42"  # 控制台脚本

通过pyproject.toml支持PEP 517构建

创建pyproject.toml：

toml
[build-system]
requires = ["maturin"]
build-backend = "maturin"

[tool.maturin]
bindings = "cffi"  # cffi/bin项目需显式指定
manylinux = "2010"  # 设置manylinux版本
sdist-include = ["path/**/*"]  # 包含额外文件到sdist

混合Rust/Python项目结构

my-project/
├── Cargo.toml
├── my_project/          # Python模块目录（与Cargo.toml中[lib] name一致）
│   ├── __init__.py
│   └── bar.py
└── src/
    └── lib.rs           # Rust代码

执行maturin develop后，Rust编译产物会被复制到my_project目录，可直接通过Python导入。

注意事项

• manylinux合规：在该镜像中构建默认启用manylinux检查，确保兼容性。若需构建非manylinux包，使用--manylinux off。
• PyPy支持：可构建PyPy wheels（pyo3绑定），但PyPy与manylinux1不兼容，需注意平台标签。
• 测试：运行测试需安装cffi和virtualenv（pip install cffi virtualenv）。