#moon_shadow

• moon.mod 信息，比如项目版本 依赖信息
• git 信息，比如生成构建工件的提交
• 编译中使用了哪个版本的 Moonbit 工具链
• 构建变体，例如： 或 debug release
• 还有更多...

#快速上手

1. 添加依赖：

moon add PaiGack/moon_shadow

2. 创建一个 shadow 包来实现该虚拟包，并让实现始终与你的 moon.mod 保持同步。只需要一个文件，shadow/moon.pkg：

import {
  "PaiGack/moon_shadow/mooninfo",
  "PaiGack/moon_shadow/gitinfo",
}

virtual(implement: "PaiGack/moon_shadow/shadow")

rule(
  name: "gen",
  command: "moon run --target native --target-dir _build/gen .mooncakes/PaiGack/moon_shadow/gen -- \"$input\" \"$output\"",
)

dev_build(rule: "gen", input: "../moon.mod", output: "generated.mbt")

3. 让读取元数据的包指向你的实现——在每一个构建路径里加上 import 和 override：

import {
  "PaiGack/moon_shadow",
}

options(
  overrides: [ "your/module/shadow" ],
)

let info = @moon_shadow.current()
println(info.name)                          // "PaiGack/moon_shadow"
println(info.version)                       // "0.1.1"
println(info.long_version())                // "PaiGack/moon_shadow@0.1.1"
println(info.dep("moonbitlang/moon_config")) // Some(...)

let git = @moon_shadow.git()
println(git.branch)                         // "main"
println(git.to_version_string())            // "main-dirty 50a396b-dirty"

#仓库结构

mooninfo/            ModuleInfo / Dependency、moon_config 解析、moon.mod 侧渲染
gitinfo/             GitInfo 类型，以及真正读 .git 的那一层：
                     仓库发现、refs、inflate、commit 对象、index、sha-1
gen/                 生成器可执行文件：读 moon.mod，调 gitinfo，写出实现文件
shadow/              虚拟包及其生成的默认实现、gen 规则
moon_shadow.mbt      公共 API：current()、git()
moon_shadow_example/ 一个使用者模块，即上述配置的完整示例

#工作原理

pub fn module_info() -> @PaiGack/moon_shadow/mooninfo.ModuleInfo
pub fn git_info() -> @PaiGack/moon_shadow/gitinfo.GitInfo

• moon.mod 的 DSL 由 moonbitlang/moon_config 解析
• git 相关信息由 gitinfo 负责直接读取 .git 中的信息解析

#需要了解的行为

• moon.pkg 声明的虚拟包必须暴露函数，不能是值。 moon 会用 pkg.mbti 类型检查虚拟包的各个实现，而一个来自其他包类型的 pub let 会通不过这个检查——尽管它在实现包里能编译。因此是 module_info() 而不是 module_info。
• 模块不能 override 自己的虚拟包。 这就是示例之所以是独立模块、 而不是 moon_shadow 内另一个包的原因。
• overrides 是 per-package 的。 每个构建路径会到达虚拟包的包 都需要自己的 options(overrides: [...])——因此示例在根包和 cmd/main 里各写了一份。
• gen 规则通过 .mooncakes 找到生成器，即 moon 为 registry 依赖准备的暂存布局——registry 使用者磁盘上本库的唯一副本，且路径 不含版本号，升级不受影响。它是内部布局：如果未来的 moon 改动了它， 规则下次运行时会以 No such file or directory 失败——在任何构建上， 包括 release，因为 pre-build 规则并非 debug 专用。提交 generated.mbt 可以把损失限制在「克隆之后又去改 moon.mod」 的场景。