Standardize Python packaging and isolate bundled MLIR

.claude/skill/pto_debug_skill.md

@@ -20,7 +20,7 @@ PTOAS 编译器调试工作流。给定一个 `.pto` 文件，AI 自动生成配
 3. 全局替换：tadd→<op>, TADD→<OP>
 4. 按 cases.py 调整 shape/dtype/eps
 5. 修改 gen_data.py 的 golden 公式
-6. 运行: python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t <op> -p build/tools/ptoas/ptoas
+6. 运行: python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t <op>
 7. 如果比对失败 → 阶段 2 TPrint 调试
 ```
 
@@ -29,7 +29,8 @@ PTOAS 编译器调试工作流。给定一个 `.pto` 文件，AI 自动生成配
 ## 前置
 
 ```bash
-source scripts/ptoas_env.sh
+LLVM_BUILD_DIR=/path/to/llvm/build ./quick_install.sh
+source "${ASCEND_HOME_PATH}/bin/setenv.bash"
 ```
 
 所有命令从 repo root 执行。
@@ -45,7 +46,7 @@ source scripts/ptoas_env.sh
 | PTO IR 样本/测试 | `test/samples/<Op>/` |
 | ST testcase | `test/tilelang_st/npu/a5/src/st/testcase/` |
 | ST 运行脚本 | `test/tilelang_st/script/run_st.py` |
-| ptoas 二进制 | `build/tools/ptoas/ptoas` |
+| ptoas 命令 | 当前 Python 环境安装的 `ptoas`（可用 `PTOAS_BIN` 覆盖） |
 | ODS 定义 | `include/PTO/IR/PTOOps.td` |
 | VPTO ODS 定义 | `include/PTO/IR/VPTOOps.td` |
 | C++ IR/Verifier | `lib/PTO/IR/PTO.cpp` |
@@ -668,22 +669,22 @@ TPrint 不匹配时，按以下顺序排查：
 
 **完整验证**：
 ```bash
-ninja -C build ptoas && \
+ninja -C build ptoas && pip install -e . --no-build-isolation && \
   rm -rf test/tilelang_st/npu/a5/src/st/build && \
-  python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t <op> -p build/tools/ptoas/ptoas
+  python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t <op>
 ```
 
 ### run_st.py 常用参数
 
 ```bash
 # 运行单个 op 的所有 case
-python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd -p build/tools/ptoas/ptoas
+python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd
 
 # 只运行特定 case
-python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd -c f32_16x64 -p build/tools/ptoas/ptoas
+python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd -c f32_16x64
 
 # 跳过构建（使用已有 build）
-python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd -p build/tools/ptoas/ptoas --without-build
+python3 test/tilelang_st/script/run_st.py -r sim -v a5 -t tadd --without-build
 ```
 
 ---

.codex/skills/build-ptoas-wsl/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: build-ptoas-wsl
-description: Build PTOAS from source inside WSL using the repository README workflow. Use when Codex is asked to build, configure, install, test, or troubleshoot ptoas/PTOAS in WSL or Ubuntu, including LLVM/MLIR llvmorg-19.1.7 setup, CMake/Ninja out-of-tree builds, pybind11 Python bindings, runtime environment variables, CLI smoke tests, or Python dialect import validation.
+description: Build PTOAS from source inside WSL using the repository README workflow. Use when Codex is asked to build, configure, install, test, or troubleshoot ptoas/PTOAS in WSL or Ubuntu, including the VPTO LLVM 21 setup, editable scikit-build-core installs, CMake/Ninja incremental builds, namespaced MLIR Python bindings, CLI smoke tests, or Python dialect import validation.
 ---
 
 # Build PTOAS in WSL
 
 ## Overview
 
-Use this skill to build PTOAS in a Linux environment under WSL. Keep the build aligned with the README: LLVM/MLIR must be `llvmorg-19.1.7`, LLVM must be built with shared libraries and MLIR Python bindings, and PTOAS is built out-of-tree against that LLVM build.
+Use this skill to build PTOAS in a Linux environment under WSL. Keep the build aligned with the README: use the VPTO-enabled LLVM branch `feature-vpto-llvm21`, build shared LLVM/MLIR libraries with Python bindings, and install PTOAS through the repository's standard editable PEP 517 workflow.
 
 Prefer running Linux build commands through WSL, not Windows PowerShell/CMake. If the user is already in a Windows checkout, either convert the path to `/mnt/c/...` for a quick build or clone/copy into the WSL ext4 filesystem for better performance.
 
@@ -31,10 +31,11 @@ wsl.exe -- bash -lc 'uname -a; cat /etc/os-release | head'
 ```bash
 sudo apt-get update
 sudo apt-get install -y git cmake ninja-build build-essential python3 python3-pip python3-dev
-python3 -m pip install --user pybind11==2.12.0 numpy
+python3 -m pip install --user \
+  'scikit-build-core>=0.12.2,<2' 'pybind11<3' 'nanobind>=2.4' numpy
 ```
 
-Pin `pybind11==2.12.0`; LLVM/MLIR Python bindings are not compatible with pybind11 3.x in this workflow.
+Keep `pybind11<3`; LLVM/MLIR Python bindings are not compatible with pybind11 3.x in this workflow.
 
 ## Environment Variables
 
@@ -45,7 +46,6 @@ export WORKSPACE_DIR=$HOME/llvm-workspace
 export LLVM_SOURCE_DIR=$WORKSPACE_DIR/llvm-project
 export LLVM_BUILD_DIR=$LLVM_SOURCE_DIR/build-shared
 export PTO_SOURCE_DIR=$WORKSPACE_DIR/PTOAS
-export PTO_INSTALL_DIR=$PTO_SOURCE_DIR/install
 
 mkdir -p "$WORKSPACE_DIR"
 ```
@@ -65,18 +65,22 @@ Build LLVM only once per WSL workspace unless the user requests a clean rebuild.
 ```bash
 cd "$WORKSPACE_DIR"
 if [ ! -d "$LLVM_SOURCE_DIR/.git" ]; then
-  git clone https://github.com/llvm/llvm-project.git "$LLVM_SOURCE_DIR"
+  git clone https://github.com/vpto-dev/llvm-project.git "$LLVM_SOURCE_DIR"
 fi
 
 cd "$LLVM_SOURCE_DIR"
 git fetch --tags
-git checkout llvmorg-19.1.7
+git checkout feature-vpto-llvm21
 
 cmake -G Ninja -S llvm -B "$LLVM_BUILD_DIR" \
   -DLLVM_ENABLE_PROJECTS="mlir;clang" \
   -DBUILD_SHARED_LIBS=ON \
   -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
+  -DLLVM_ENABLE_ASSERTIONS=ON \
   -DPython3_EXECUTABLE="$(which python3)" \
+  -DPython_EXECUTABLE="$(which python3)" \
+  -Dpybind11_DIR="$(python3 -m pybind11 --cmakedir)" \
+  -Dnanobind_DIR="$(python3 -m nanobind --cmake_dir)" \
   -DCMAKE_BUILD_TYPE=Release \
   -DLLVM_TARGETS_TO_BUILD="host"
 
@@ -102,42 +106,39 @@ if [ ! -d "$PTO_SOURCE_DIR/.git" ]; then
 fi
 
 cd "$PTO_SOURCE_DIR"
-export PYBIND11_CMAKE_DIR="$(python3 -m pybind11 --cmakedir)"
+PYTHON_BIN=python3 \
+LLVM_BUILD_DIR="$LLVM_BUILD_DIR" \
+PTO_BUILD_DIR="$PTO_SOURCE_DIR/build" \
+  ./quick_install.sh
 
-cmake -G Ninja \
-  -S . \
-  -B build \
-  -DLLVM_DIR="$LLVM_BUILD_DIR/lib/cmake/llvm" \
-  -DMLIR_DIR="$LLVM_BUILD_DIR/lib/cmake/mlir" \
-  -DPython3_EXECUTABLE="$(which python3)" \
-  -DPython3_FIND_STRATEGY=LOCATION \
-  -Dpybind11_DIR="$PYBIND11_CMAKE_DIR" \
-  -DMLIR_ENABLE_BINDINGS_PYTHON=ON \
-  -DMLIR_PYTHON_PACKAGE_DIR="$LLVM_BUILD_DIR/tools/mlir/python_packages/mlir_core" \
-  -DCMAKE_INSTALL_PREFIX="$PTO_INSTALL_DIR"
-
-ninja -C build
-ninja -C build install
+# Reuse the persistent CMake tree for incremental builds and checks.
+ninja -C "$PTO_SOURCE_DIR/build" check-pto
 ```
 
 Expected outputs:
 
 ```bash
 test -x "$PTO_SOURCE_DIR/build/tools/ptoas/ptoas"
 test -x "$PTO_SOURCE_DIR/build/tools/ptobc/ptobc"
-find "$PTO_SOURCE_DIR/build/python" -name '_pto.cpython-*.so' -print
-test -f "$PTO_INSTALL_DIR/mlir/dialects/pto.py"
+test -n "$(find "$PTO_SOURCE_DIR/build/python/ptoas" \
+  -name '_core.cpython-*.so' -print -quit)"
+test -f "$PTO_SOURCE_DIR/build/python/ptoas/mlir/dialects/pto.py"
 ```
 
 ## Runtime Environment
 
-After installation, set the runtime paths before using `ptoas`, `ptobc`, or Python imports.
+`quick_install.sh` performs an editable install into the selected Python environment.
+Use the installed `ptoas` console script and import `ptoas.mlir` directly. Do not add
+LLVM's top-level `mlir_core` package or the deleted top-level `pto` package to
+`PYTHONPATH`.
+
+Only when invoking artifacts directly from the CMake build tree, expose that single
+tree explicitly:
 
 ```bash
-export MLIR_PYTHON_ROOT=$LLVM_BUILD_DIR/tools/mlir/python_packages/mlir_core
-export PTO_PYTHON_ROOT=$PTO_INSTALL_DIR
-export PYTHONPATH=$MLIR_PYTHON_ROOT:$PTO_PYTHON_ROOT:$PYTHONPATH
-export LD_LIBRARY_PATH=$LLVM_BUILD_DIR/lib:$PTO_INSTALL_DIR/lib:$LD_LIBRARY_PATH
+export PTOAS_BUILD_PYTHON_ROOT=$PTO_SOURCE_DIR/build/python
+export PYTHONPATH=$PTOAS_BUILD_PYTHON_ROOT:$PYTHONPATH
+export LD_LIBRARY_PATH=$LLVM_BUILD_DIR/lib:$PTO_SOURCE_DIR/build/lib:$LD_LIBRARY_PATH
 export PATH=$PTO_SOURCE_DIR/build/tools/ptoas:$PTO_SOURCE_DIR/build/tools/ptobc:$PATH
 ```
 
@@ -160,8 +161,8 @@ Validate Python dialect loading:
 
 ```bash
 python3 - <<'PY'
-from mlir.ir import Context, Module, Location
-from mlir.dialects import pto
+from ptoas.mlir.ir import Context, Module, Location
+from ptoas.mlir.dialects import pto
 
 with Context() as ctx, Location.unknown():
     pto.register_dialect(ctx, load=True)
@@ -172,8 +173,16 @@ PY
 
 ## Troubleshooting
 
-- `def_property family does not currently support keep_alive`: reinstall `pybind11==2.12.0`, clear the affected CMake cache if needed, and reconfigure.
-- CMake cannot find LLVM or MLIR: confirm `LLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm` and `MLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir` exist and were produced by the `llvmorg-19.1.7` build.
-- Python cannot import `mlir.dialects.pto`: re-export `PYTHONPATH` with MLIR core first and PTO install second, and confirm `_pto.cpython-*.so` exists under MLIR's `_mlir_libs`.
-- Runtime linker errors for LLVM or PTO libraries: re-export `LD_LIBRARY_PATH=$LLVM_BUILD_DIR/lib:$PTO_INSTALL_DIR/lib:$LD_LIBRARY_PATH`.
+- `def_property family does not currently support keep_alive`: reinstall a supported
+  `pybind11<3`, clear the affected CMake cache if needed, and reconfigure.
+- CMake cannot find LLVM or MLIR: confirm
+  `LLVM_DIR=$LLVM_BUILD_DIR/lib/cmake/llvm` and
+  `MLIR_DIR=$LLVM_BUILD_DIR/lib/cmake/mlir` exist in the
+  `feature-vpto-llvm21` build.
+- Python cannot import `ptoas.mlir.dialects.pto`: confirm the editable install is
+  active, then check `build/python/ptoas/_core.cpython-*.so` and
+  `build/python/ptoas/mlir/_mlir_libs/_mlir*.so` in the same build tree. For
+  direct build-tree imports, prepend only `build/python` to `PYTHONPATH`.
+- Runtime linker errors for LLVM or PTO libraries: re-export
+  `LD_LIBRARY_PATH=$LLVM_BUILD_DIR/lib:$PTO_SOURCE_DIR/build/lib:$LD_LIBRARY_PATH`.
 - Builds are very slow under `/mnt/c`: move the workspace into the WSL Linux filesystem, for example `$HOME/llvm-workspace`.