系列目录 · 工程与交付 · Read in English
工具在开发目录里运行得很好。把安装包解压到另一处，卷积能过，几个简单算子也能过，直到编译一个非线性激活，Python 才报找不到模块。
“可执行文件不是都打包了吗？”
问题在于，可执行文件不一定是编译器的全部。它可能嵌入 Python，调用某个查表参数生成器。生成器又是随着源码目录存在的资源。如果源码路径在编译时被硬编码，程序就像一个搬家后仍给旧地址点外卖的人。
为什么基础 smoke test 没看见问题
--help 可以证明程序启动，不能证明每条编译路径都找得到运行资源。一次只包含加法的编译也可能完全不触发查表生成。
非线性算子的 lowering 往往需要把数学函数转成近似参数。若这一步通过 Python 模块完成，错误会在“真正需要拟合”的时候才出现。二进制文件本身可以正常加载，因此排查首先看到的是一个算子问题，实际缺的是资源定位契约。
所审阅的变更移除了编译定义中的源树绝对路径，改为根据可执行文件位置及 Python 搜索路径寻找配套模块，同时在安装和打包阶段把该模块列为必要产物。
三种起点，哪一种可信
寻找资源常见的起点有当前工作目录、源代码目录和工具安装目录。
当前工作目录由调用者决定。用户从任意文件夹运行编译器都很正常，因此把它当安装位置通常过于脆弱。
源代码目录对开发者方便，却不应成为发布程序的隐含依赖。交付包旁边未必有源码，即便有，也可能是另一版。
工具所在目录更适合描述安装布局。例如工具在 prefix/bin，模块在 prefix/python，两者关系可以随整个包一起移动。开发树也可能有不同的相对布局，这需要明确支持，而不是在整个磁盘上盲目搜索。
教学上，可以把过程写成：
1 | 定位当前工具 |
这不是原实现的逐行复制，而是其可推广的机制。
嵌入 Python 时，谁才是“主程序”
还有一个容易漏掉的入口：从 Python 扩展调用编译器。此时进程可执行文件可能是 Python 解释器，而不是安装包里的编译器工具。
如果只根据主程序目录推导资源，原生命令行工具修好了，Python 绑定仍然会失败。代码差异因此也处理了宿主 Python 的搜索路径，从其中的目录确认是否有配套模块。
但遍历搜索路径并不代表应该无条件相信所有候选。首先要确认目标文件存在，避免添加大量无效目录；还要处理 Python API 返回的错误和非字符串路径项。若路径已经存在，重复添加没有价值。
搜索顺序也属于行为。显式环境路径、包内资源与当前解释器环境之间谁优先，会影响同名模块的选择。这里能确认的是修改提供了多个合理定位来源；不能把它概括成“永远不会导入错误版本”。若项目要求更强的模块身份约束，还应另外校验版本或来源。
真正有意思的是负向测试
最有说服力的回归并不是再次在源码目录里运行，而是刻意让旧假设不成立。
阅读到的测试会创建临时目录，把工具和所需 Python 模块放入新的相对位置，清理若干与源树有关的环境变量，然后执行真正会生成查表参数的编译路径。它还检查导入来源，避免程序悄悄回到原源码目录。
随后，测试把新位置中的模块隐藏，再运行一次，要求出现明确的导入失败。
后一半很重要：如果删除包内模块以后程序仍然成功，就说明测试环境还有其他来源在帮忙。这样的成功反而证明测试没有隔离出想验证的依赖。
因此，这个测试同时回答两个问题：“正确资源在新位置时能不能用？”以及“正确资源不在时，会不会偷用旧资源？”
这个测试也有自己的边界
所阅读的测试保留了配置好的原生动态库搜索路径，因为它针对的是 Python 资源搬迁。不能把这解释成整个发布包完全脱离开发环境。
这恰好说明，测试范围写清楚非常重要。一个专注于资源定位的测试，不需要同时解决所有 ABI、系统库与运行时兼容问题；但报告也不能扩大它的证明范围。
可以把验证层拆开：
| 层次 | 对应检查 |
|---|---|
| 原生加载 | 二进制和扩展所需动态库是否可解析 |
| Python 定位 | 导入来自目标安装树而非源树 |
| 实际功能 | 至少一条真实查表生成路径能够走通 |
| 缺件诊断 | 缺少模块时明确失败 |
| 多入口 | 命令行与 Python 宿主分别覆盖 |
这些层彼此关联，却不能互相替代。原生加载测试成功，不证明查表模块存在；查表生成成功，也不证明所有非线性函数的近似误差合格。
不要用“加一个大 PYTHONPATH”结束故事
给环境变量塞进所有可能目录，往往能让问题暂时消失，却会让错误版本更难发现。
尤其当开发树和安装树同时存在时，调试期间修改的 Python 文件可能影响发布包行为，而其他用户拿不到同一修改。这个状态比直接报错更难复现，因为程序依赖了没有写进交付清单的东西。
更清楚的策略是：定义少量受支持布局，随包安装必要资源，检查模块身份或来源，把显式覆盖作为可解释的接口。找不到就给出可以定位的失败，而不是无限回退。
安装阶段的必要文件检查也不多余。提前发现少打包一个模块，比让用户跑到某个特殊算子才失败更省排障成本。
搬迁能力应该如何讨论性能
路径检查和一次性导入可能带来启动成本，但不能凭感觉认定它是瓶颈。拟合、解析与整个编译过程的耗时往往处在不同量级，应测量后再优化。
可以建议分别记录首次导入时间、同进程重复调用、查表参数生成和总编译时间。若要缓存结果，还必须把输入域、量化参数和近似模式纳入缓存键，不能因为函数名相同就复用一张表。
它修复的是资源身份和位置之间的关系。编译器能够搬家，是因为依赖关系被表达出来，而不是因为碰巧还记得开发者的旧地址。
If you like this blog or find it useful for you, you are welcome to comment on it. You are also welcome to share this blog, so that more people can participate in it. All the images used in the blog are my original works or AI works, if you want to take it,don't hesitate. Thank you !