#moon_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"

#为什么 git 信息不是运行时采集

moon.mod ----(gen rule)---> shadow/generated.mbt --(compile)--> current()
git 命令 ----(gen rule)--->                       --(compile)--> git()

#在自己的模块中使用

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 js --target-dir _build/gen .mooncakes/PaiGack/moon_shadow/gen/main.mbt -- --meta-path PaiGack/moon_shadow/mooninfo --git-path PaiGack/moon_shadow/gitinfo \"$input\" \"$output\"",
)

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

3. 让读取元数据的包指向你的实现——在每一个构建路径会经过 @moon_shadow.current() / @moon_shadow.git() 的 moon.pkg 里加上 import 和 override：

import {
  "PaiGack/moon_shadow",
}

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

#生成器跑在哪个后端

#工作原理

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

#API

#仓库结构

mooninfo/            ModuleInfo / Dependency、moon_config 解析、moon.mod 侧渲染
gitinfo/             GitInfo 类型、"怎么把一段输出解释成字段"的纯逻辑
gen/                 生成器可执行文件：读 moon.mod、跑 git、写出实现文件
shadow/              虚拟包及其生成的默认实现、gen 规则
moon_shadow.mbt      公共 API：current()、git()
moon_shadow_example/ 一个使用者模块，即上述配置的完整示例

#需要了解的行为

• moon.pkg 声明的虚拟包必须暴露函数，不能是值。 moon 会用 pkg.mbti 类型检查虚拟包的各个实现，而一个来自其他包类型的 pub let 会通不过这个检查——尽管它在实现包里能编译。因此是 module_info() 而不是 module_info。
• current() / git() 描述的是提供实现的人，不是调用它的人。 moon_shadow_example/ 展示了两种情况：没有 override 时得到库 baked-in 的值，有 override 时得到你自己的。
• 模块不能 override 自己的虚拟包。 这就是示例之所以是独立模块、 而不是 moon_shadow 内另一个包的原因。
• 来自 registry 的依赖不会运行构建规则。 MoonBit 会跳过 registry 依赖被消费时的 pre-build 步骤，所以本库无法替你完成模块的配置： 上面的 shadow 包需要你自己创建，里面的 gen 规则负责让 generated.mbt 保持新鲜。库在 shadow/ 里附带的只是给从不 override 的使用者的默认实现——也就是说 moon add 完，git() 拿到的是 本库烘焙进去的值，不是你的仓库。想要自己仓库的 git 信息，就得自己建 shadow 包和 gen 规则。
• 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」 的场景。
• dirty 只看已跟踪文件。 git status --porcelain --untracked-files=no。 generated.mbt 是入库的，用默认行为的话「生成」这个动作本身就会让工作区 变脏，然后永远是脏的。
• git 不在规则输入里。 dev_build(input: "../moon.mod") 只看 moon.mod， 这是有意的：否则每次 commit 都会让生成物失效、触发重编。代价是 git 变了 不会自动重新生成——想让 git_info() 跟上新 commit，moon clean 一下让 generated.mbt 重新生成即可。发布构建本来就在全新的 checkout 上跑，不受 影响。
• 生成内容对同一份输入完全确定（不写时间戳、不写随机值），所以 「重新生成 = 无 diff」，CI 里那句 git diff --exit-code 才有意义。
• 非 git 环境不让构建失败。 不是仓库、没装 git，生成器照常写文件， available = false、其余字段为空串 / 0，并在 stdout 上说一句。
• 所有 git 调用带 GIT_OPTIONAL_LOCKS=0，避免抢 index.lock 卡住用户 自己的 git commit。
• 转义只解码一次。 moon_config 返回的字符串字面量是源码原始 形式（"a \"b\"" 得到 a \"b\"），因此 mooninfo 会在重新生成前 做一次反转义；否则每次重新生成都会让反斜杠翻倍。unescape 与 mooninfo::quote 互为逆运算，\u{...} / \xNN / \oNNN / 续行 都在内，所以「重新生成 = 无 diff」对含转义的 moon.mod 也成立。
• 生成物不带尾逗号。 早先的渲染器刻意复刻 moon fmt 的尾逗号， 但 moon fmt 对字面量的输出并不带它；生成的代码现在就是格式化后的样子， 提交前不再需要手工格式化。
• 包名。 mooninfo 装的是 moon.mod 的一半，gitinfo 装 git 的一半， 命名对齐；0.1.x 里的 core 包在 0.2.0 改名为 mooninfo，升级时把 moon.pkg 里的 PaiGack/moon_shadow/core 换成 PaiGack/moon_shadow/mooninfo 并重新生成一次 generated.mbt 即可。