Mill构建工具中Cross.Module模块路径配置的演进

在Mill构建工具中，Cross.Module是一个用于支持跨构建的重要组件。随着Mill版本从0.12.x向1.0演进，其模块路径配置方式也发生了变化，这给开发者带来了一些困惑。

历史背景

在Mill 0.12.x版本中，开发者通常通过重写millSourcePath属性来定义跨模块的源路径。典型用法如下：

trait FooModule extends Cross.Module[String] {
  def millSourcePath = super.millSourcePath / crossValue
  def sources = Task.Sources(millSourcePath)
}

然而，从Mill 0.12.11开始，millSourcePath被标记为已弃用(deprecated)，官方推荐使用新的moduleDir属性替代。但问题在于，在0.12.x版本中moduleDir被声明为final，无法被重写。

技术解析

这一变化背后有几个关键点需要理解：

1. 二进制兼容性考虑：Mill 0.12.x需要保持与早期版本(特别是0.11.0)的二进制兼容性。moduleDir在0.11.0中并不存在，因此不能假设第三方模块会使用或重写它。

2. 过渡期设计：在0.12.x中，moduleDir只是作为millSourcePath的一个便捷访问器，被声明为final以确保兼容性。此时重写millSourcePath仍然是安全的。

3. 1.0版本的改变：在Mill 1.0中，moduleDir不再是final，可以被重写，而millSourcePath则被完全移除。

开发者应对策略

对于不同Mill版本的开发者：

• 使用Mill 0.12.x：可以安全地继续重写millSourcePath，虽然会收到弃用警告，但这是过渡期的正常现象。

• 计划迁移到1.0：需要准备将所有millSourcePath的重写改为moduleDir的重写。

• 开发跨版本模块：需要特别注意二进制兼容性问题，避免依赖特定版本的行为。

设计决策分析

Mill团队在这一变更中面临几个技术挑战：

1. 平滑迁移：如何在保持向后兼容的同时引导用户使用新API。

2. 命名一致性：millSourcePath到moduleDir的改名是为了提高API的一致性和可读性。

3. 二进制兼容性：在支持旧模块的同时推进新功能。

虽然弃用警告在0.12.x中看似没有立即的迁移行动，但它确实为1.0版本的迁移做了重要准备。当用户升级到1.0时，编译器错误会引导他们回到这个弃用警告，从而理解需要进行的更改。

最佳实践建议

1. 对于新项目，建议直接使用Mill 1.0及以上的版本。

2. 维护中的项目如果还在使用0.12.x，可以暂时忽略millSourcePath的弃用警告，但应在项目计划中安排向1.0迁移的工作。

3. 开发跨构建模块时，建议添加清晰的版本兼容性说明。

Mill构建工具的这一变更展示了大型项目演进过程中API设计的典型挑战和解决方案，理解这些背景有助于开发者更好地使用和维护基于Mill的构建系统。