适配pyproject.toml的Linux构建系统选型咨询（非PyPI项目）

Setuptools是Python生态的标准构建工具，灵活度拉满，完全兼容pyproject.toml，能轻松实现系统包检查、自定义文件操作等需求，同时支持生成wheel包，完全匹配你的场景。

核心配置步骤 #

1. 编写pyproject.toml #

在文件中指定构建依赖、项目依赖，同时添加自定义配置项（系统包列表、外部资源信息）：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
version = "0.1.0"
dependencies = [
    "numpy>=1.21",
    "scikit-learn>=1.0"
]

# 自定义配置：系统依赖与外部资源
[tool.your-project]
system-packages = ["gfortran", "libopenblas-dev", "liblapack-dev"]
external-archives = [
    { url = "https://example.com/your-archive.tar.gz", dest = "src/your_project/external", extract = true }
]

2. 实现自定义构建逻辑（setup.py） #

创建setup.py，通过继承setuptools.Command实现前置构建操作：

import os
import subprocess
import tarfile
from setuptools import setup, Command
from setuptools.config import read_configuration

class PrepareBuild(Command):
    description = "检查系统依赖、下载外部资源"
    user_options = []

    def initialize_options(self):
        pass

    def finalize_options(self):
        self.config = read_configuration("pyproject.toml")["tool"]["your-project"]

    def run(self):
        # 检查Debian系系统包
        system_pkgs = self.config["system-packages"]
        if system_pkgs:
            print(f"检查系统依赖：{', '.join(system_pkgs)}")
            result = subprocess.run(
                ["dpkg", "-l"] + system_pkgs,
                capture_output=True,
                text=True
            )
            if result.returncode != 0:
                missing = [pkg for pkg in system_pkgs if pkg not in result.stdout]
                raise RuntimeError(
                    f"缺少依赖包：{', '.join(missing)}，请执行：sudo apt-get install {' '.join(missing)}"
                )

        # 下载并解压外部归档
        for archive in self.config["external-archives"]:
            url = archive["url"]
            dest_dir = archive["dest"]
            extract = archive.get("extract", False)
            os.makedirs(dest_dir, exist_ok=True)
            archive_path = os.path.join(dest_dir, os.path.basename(url))

            print(f"下载资源：{url} -> {archive_path}")
            subprocess.run(["curl", "-o", archive_path, url], check=True)

            if extract:
                print(f"解压归档：{archive_path} -> {dest_dir}")
                with tarfile.open(archive_path, "r:*") as tar:
                    tar.extractall(path=dest_dir)
                os.remove(archive_path)

setup(
    cmdclass={
        "prepare_build": PrepareBuild,
    }
)

3. 执行构建流程 #

• 先运行前置准备命令：python setup.py prepare_build
• 生成wheel包：python -m build --wheel
• 安装项目：pip install .

备选方案：Hatch #

如果觉得Setuptools的自定义命令稍显繁琐，可以用Hatch。它支持在pyproject.toml中定义构建钩子，执行前置操作，同样能生成wheel包。

核心配置示例 #

[build-system]
requires = ["hatchling>=1.10"]
build-backend = "hatchling.build"

[project]
name = "your-project-name"
version = "0.1.0"
dependencies = ["numpy>=1.21", "scikit-learn>=1.0"]

[tool.hatch.build.hooks.custom]
script = "scripts/build_prep.py"

# 自定义配置项
[tool.your-project]
system-packages = ["gfortran", "libopenblas-dev"]
external-archives = [{ url = "https://example.com/archive.tar.gz", dest = "src/external" }]

然后编写scripts/build_prep.py脚本，实现和Setuptools方案中一致的系统包检查、资源下载逻辑即可。

排除其他工具的原因 #

• Poetry：优先避免，且它核心定位是依赖管理与PyPI发布，自定义构建灵活性不足，没必要强行使用。
• PDM：侧重依赖管理，自定义构建能力不如Setuptools，对于你的简单需求来说过重。
• Flit：功能简洁，但不支持复杂的自定义构建操作，无法满足系统包检查、外部资源下载的需求。

内容的提问来源于stack exchange，提问作者silpol