op_optimization/tilelang_maca_install_guide.md

TileLang MACA 安装与验证指南

环境：MetaX C500 / MACA 3.7.2.1 / Python 3.12 / Conda

源码：/data/tilelang-metax（dev 分支）

---

1. 前置条件

• MACA 已安装在 /opt/maca（包含 libmcruntime.so 等运行时库）
• Python 3.12 + Conda 环境

---

2. 编译安装 tilelang（启用 MACA 后端）

cd /data/tilelang-metax
rm -rf build
export USE_MACA=ON
pip install -e . -v

编译产物位于 build/lib/，包含：

• libtilelang.so — 注册 maca target kind
• libtvm.so — TVM 运行时

---

3. 修复 .pth 文件（关键步骤）

tilelang 的 editable install 生成的 .pth 文件缺少 tvm Python 包的正确路径。

文件位置：/opt/conda/lib/python3.12/site-packages/_tilelang_editable.pth

修改：将其中一行 /data/tilelang-metax/3rdparty/tvm 改为：

/data/tilelang-metax/3rdparty/tvm/python

修改后的文件内容应为：

import _tilelang_editable
/data/tilelang-metax
/data/tilelang-metax
/data/tilelang-metax/3rdparty/tvm/python
/data/tilelang-metax/3rdparty/tvm
/data/tilelang-metax/3rdparty/tvm
/data/tilelang-metax/3rdparty/tvm/3rdparty/dmlc-core
/data/tilelang-metax/3rdparty/tvm
/data/tilelang-metax/3rdparty/cutlass
/data/tilelang-metax/3rdparty/cutlass
/data/tilelang-metax/3rdparty/composable_kernel
/data/tilelang-metax/3rdparty/composable_kernel

---

4. 验证

4.1 基础导入

python -c "import tilelang; print(tilelang.__version__)"
# 预期输出：0.1.9+maca.gitee6db437

4.2 MACA Target 验证

必须先 import tilelang，因为它会加载 libtilelang.so（注册 maca target）：

python -c "
import tilelang
from tvm.target import Target
t = Target('maca')
print(t)
"
# 预期输出：
# maca -keys=maca,gpu -max_local_memory_per_block=4095 -max_num_threads=1024
#   -max_shared_memory_per_block=65536 -max_threads_per_block=1024
#   -mcpu=xcore1000 -mtriple=mxc-metax-macahca -thread_warp_size=64

---

5. 常见问题

问题	原因	解决
ModuleNotFoundError: No module named 'tvm'	.pth 文件缺少 3rdparty/tvm/python 路径	修改 .pth 文件（见步骤 3）
Target kind "maca" is not defined	未先 import tilelang，libtilelang.so 未加载	先 import tilelang 再使用 Target('maca')
Target kind "maca" is not defined（已 import tilelang）	编译时未启用 MACA	用 USE_MACA=ON 重新编译（见步骤 2）
编译报 ninja: error: Makefile	build/ 目录残留旧 Makefile	rm -rf build 后重新编译