Standardize Python packaging and isolate bundled MLIR

[mouliangyu]

背景

PTOAS 原先通过自定义 PEP 517 backend、setup.py、wheel bootstrap、运行时路径扫描和多套发布脚本维护 Python 包。这些代码重复承担了标准打包工具已有的 metadata、editable install、console script、wheel 组装和 native dependency repair，也使 CLI、PTODSL、CI、wheel 和 standalone archive 显式依赖源码树、LLVM build tree 或旧 install tree 的内部布局。

同时，直接发布顶层 mlir 包会与进程中的其他 MLIR Python distribution 冲突。PTOAS 需要拥有一套自洽的 MLIR Python runtime，并让 compiler native module 与 Python bindings 共享同一套 MLIR CAPI。

本 PR 将 Python 构建与发布链路收敛到 scikit-build-core、AddMLIRPython 和标准平台 repair 工具，并把 PTOAS 自带的 MLIR runtime 隔离到 ptoas.mlir。

修改内容

• 使用 scikit-build-core 作为标准 PEP 517/660 backend：
  • 根项目发布 ptoas；
  • packaging/ptoas-vmi 发布 ptoas-vmi；
  • 两个 distribution 共享 CMake 构建图、Python package 和 console script；
  • 支持标准 wheel 与 editable install，删除自定义 backend、setup.py 和 wheel bootstrap。
• 将 PTOAS 自带的 MLIR Python runtime 放到项目命名空间：
  • public import 改为 ptoas.mlir 和 ptoas.mlir.dialects.pto；
  • 设置 MLIR_PYTHON_PACKAGE_PREFIX=ptoas.mlir. 和独立 nanobind domain；
  • 不再安装或兼容 alias 到顶层 mlir。
• 使用 AddMLIRPython 的声明式 source graph 构建 MLIR Python package：
  • 显式选择 PTOAS/PTODSL 使用的 upstream dialect；
  • 使用标准 site initializer 注册 dialect；
  • 保留一个 package-owned PTOASPythonCAPI；
  • 仅对上游 MLIR/nanobind 生成源码局部免除 -Werror，PTOAS 自有代码继续保持 -Werror。
• 将 native compiler 统一为 ptoas._core：
  • LLVM driver sources 作为 object library 保持 LLVM 的 RTTI/exception 编译模式；
  • Python binding translation units 保持 pybind11 所需的 RTTI/exception；
  • CLI 和 PTODSL 通过正常 Python import 使用 _core，不再扫描 native library 路径。
• 统一 CLI 与运行时路径契约：
  • wheel console script 使用 ptoas._cli:main；
  • build/install/archive wrapper 只添加各自 tree 对应的 Python root；
  • PTODSL 查找编译器时只接受显式 PTOAS_BIN，否则使用标准 PATH；
  • 删除 _bootstrap.py、_runtime_entry 和跨源码/build/install tree 的路径猜测。
• 标准化版本与 release 流程：
  • ptoas-vmi 的 PEP 621 version 是 VMI distribution 的唯一版本源；
  • scikit-build-core 通过 SKBUILD_PROJECT_VERSION_FULL 将版本传给 CMake/CLI；
  • 删除 PTOAS_VMI_VERSION 扫描、同步脚本和自动 patch bump；
  • Linux wheel 使用 auditwheel repair，macOS wheel 使用 delocate-wheel；
  • payload 校验按平台识别 .so/.dylib common CAPI。
• 标准化开发环境与 CI：
  • quick_install.sh 使用标准 editable install；
  • CI 与 simulator CI 使用 workflow-owned venv 和 editable install；
  • lit 从 CMake 获取匹配的 MLIR Python package；
  • editable native targets 显式使用外部 LLVM build RPATH，wheel 保持 package-relative RPATH 并交给 repair 工具处理；
  • wheel payload、isolated install、import、CLI 和编译流程由 workflow 验证。
• 重构 standalone compiler archive：
  • 由 PTOAS_Python 和 PTOAS_CompilerArchive 两个 CMake component 组装受控 install tree；
  • install-time deployment 使用 CMake target 元数据确定 _core 和 PTOASPythonCAPI；
  • 使用 file(GET_RUNTIME_DEPENDENCIES) 收集外部依赖并检查 unresolved/ABI 冲突；
  • Linux 生成 archive-relative $ORIGIN RPATH，macOS 使用 delocate-path；
  • 删除原有 Linux/macOS shell dependency collectors。
• 同步更新 README、构建文档、设计文档、PTODSL/TileLang imports、samples 和测试。

验证

在重放到最新 main 后：

• PEP 517 metadata：ptoas 0.53、ptoas-vmi 0.1.4。
• 四个 workflow YAML 均可解析，旧 VMI version 脚本/变量无残留引用。
• VMI editable install 增量构建成功；清除 LD_LIBRARY_PATH/PYTHONPATH 后：
  • ptoas.mlir.ir、PTO dialect 和 ptoas._core 可导入；
  • ptoas --version 输出 ptoas vmi 0.1.4。
• 实际 repaired VMI wheel payload 校验通过。
• git diff --check 通过。
• PR386 license checker 检查 273 个变更源码/脚本文件，全部通过。

同一变更在重放前的 release dry-run 中完成了 Linux 全矩阵验证：

• Python 3.10/3.11/3.12 × x86_64/aarch64，共 6 个 ptoas_vmi-0.1.4 wheel；
• 全部通过 build、payload validation、auditwheel repair、隔离安装测试和 artifact 上传；
• 额外下载 Python 3.11 x86_64 wheel，在本地新 venv 中清除外部库路径后安装、import 和 CLI 验证通过。

范围说明

• ptoas 与 ptoas-vmi 会安装相同的顶层 Python package 和 console script，因此两个 distribution 互斥，不应装入同一环境。
• macOS release dry-run 已验证修复后的 .dylib payload validation，并进入 delocate repair；完整 macOS matrix 由本 PR 的 workflow 继续覆盖。

[mouliangyu]

[P1] The ptoas-vmi sdist is not self-contained. pyproject.toml (line 44) references CMake and packages through ../... Building the sdist produced only pyproject.toml and PKG-INFO; rebuilding a wheel from it failed because the referenced CMake source tree was absent. Any source installation or package-index sdist fallback will fail. The VMI project must stage/include its complete sources and use paths internal to the sdist.
[P1] TileLang text-to-module conversion imports the removed package. lowering_backend.py (line 77) still imports pto.dialects.pto. The new distributions install only ptoas, ptodsl, and tilelang_dsl, so LoweringResult(text=...).as_module() raises ModuleNotFoundError in a clean install. It should import ptoas.mlir.dialects.pto. Existing tests pass because none calls as_module() on a text result.
[P2] The repository build skill still validates the deleted package layout. SKILL.md (line 128) expects _pto.cpython-*.so and $PTO_INSTALL_DIR/mlir/dialects/pto.py, then configures PYTHONPATH around LLVM’s top-level mlir_core. This PR now produces ptoas/_core and ptoas/mlir, so the documented workflow fails its output checks and contradicts the isolation contract.

[mouliangyu]

已在 0616b6dcd 修正这三处问题：

1. VMI 源码包不自包含

   • 删除了 packaging/ptoas-vmi/pyproject.toml 这份依赖 ../.. 的重复配置，根目录 pyproject.toml 仍是唯一的完整构建配置。
   • VMI wheel 构建时，prepare_source.py 通过 git archive 导出完整的已跟踪源码树，再对 staging 中的根 pyproject.toml 应用一份只包含 VMI distribution 差异的 patch（包名、静态版本、CLI label 等）。wheel 直接从这个 staging 目录构建，不再引用源码树外路径，也不需要手工枚举 CMake/源码目录。
   • 这段 staging 逻辑仅在 vmi-v* release 或手动选择 release_kind=vmi 时执行；普通 PR/push 不执行 VMI staging。sdist 不纳入发布物或门禁，也没有新增 PyPA build 依赖。
   • 本地验证 staging 后元数据为 ptoas-vmi 0.1.4，关键源码/CMake 文件齐全，pyproject.toml 无 ../。另外独立做过一次完整的 sdist -> 解包 -> wheel 验证，解包后的源码可单独构建，证明 staging 本身是自包含的。

2. TileLang 仍引用旧命名空间

   • 已改为 ptoas.mlir.dialects.pto。
   • 删除了对 func/arith/scf 的显式注册；这些 bundled upstream dialect 已由 PTOAS MLIR site initializer 注册，只显式注册项目自有的 PTO dialect。
   • 增加了直接调用 LoweringResult(text="module {}").as_module() 的回归测试，本地通过（1 test）。

3. WSL skill 与当前包结构不一致

   • 已更新为 LLVM 21、quick_install.sh、ptoas._core 和 ptoas.mlir 的当前安装/导入约定，移除了旧 _pto 与顶层 mlir 布局描述。
   • skill validator 本地通过。

补充验证：两个 workflow YAML 均可解析；相关 Python 文件 py_compile 通过；VMI metadata patch 的 git apply --check 通过；git diff --check 通过。