豫言 / 构建编排 @ 0.1.0

以普通豫言声明构建目标、依赖与步骤，并行调度，按输入修改时间跳过已最新的目标。

# 构建编排

用普通豫言声明构建目标、依赖与步骤，由本库并行调度，并按输入跳过已最新的目标。语言仓的构建目标写在 `应用/豫构/仓库目标。豫`，由豫构调用本库运行：在仓库根目录执行 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 自举|测试|打包|清理|全部`，或用 `… yy豫构.wasm 目标 名…` 运行任意目标。其他仓库写一个构建程序（可执行包，如云仓的“云仓构建”），列出全部目标后调用 `构建程序主函数`。仓库里不再保留 shell 脚本。

## 用法

```text
寻观「标准库」之书。
寻观「构建编排」之书。

「目标们」乃「列」于「构建目标」也。
「目标们」者
  「列」【
    （「目标」
      于『甲』                           「：名称：」
      于『构建 yy甲.wasm』               「：说明（--列出 时显示）：」
      于（「罄」授以「字符串」）         「：依赖的目标名：」
      于（「列」【（「命令步」于『./yy豫构.wasm』于（「列」【『文件』，『甲。豫』，『--输出』，『yy甲.wasm』】））】）
      于（「列」【（「文件输入」于『甲。豫』）】）
      于（「列」【『yy甲.wasm』】））
  】
也。

「构建程序主函数」于「目标们」。
```

构建程序的命令行：`程序 [目标…] [-j 并发] [--强制] [--不连带] [--列出]`。不给目标时执行名为“全部”的目标；`--强制` 忽略缓存；`--不连带` 只执行所列目标本身（所列目标之间的依赖仍按顺序）；`--列出` 打印全部目标及说明。

## 目标与步骤

`「目标」于 名称 于 说明 于 依赖们 于 步骤们 于 输入们 于 输出们`。同一目标的步骤依次执行；不同目标在依赖满足后并行执行，上限由 `-j` 决定（默认在线处理器数量）。任一步骤失败即停止派发新步骤，并以非零退出码结束。

步骤：

- `命令步 程序 参数们`：运行外部命令，参数原样传递，不经 shell。
- `目录内命令步 目录 程序 参数们`：在指定工作目录里运行（启动时切换目录，启动后立即切回）。
- `限时命令步 秒数 程序 参数们`：有 `timeout` 命令时限时运行，超时即终止。
- `函数 说明 函数体`：在构建程序里直接执行一个豫言函数；说明计入缓存键。`写文件步 路径 内容` 基于它。
- `复制文件步`、`相同步`（逐字节比较）、`建目录步`、`删除步`：常用命令的简写。
- `独占 组名 步骤`：同一组的步骤按目标的拓扑顺序逐个执行，互不并发。共用同一编译缓存的豫构调用（以及内部再调用豫构的测试）必须放进同一组，满足“同一缓存同一时刻只跑一个构建”。

## 缓存

输入是 `文件输入 路径` 或 `目录输入 目录 后缀们 排除片段们`（递归，略去以点开头的名字与 `_v0` 目录；后缀为空表示全部文件）。输入与输出都非空的目标可以缓存：缓存键由步骤描述、每个输入文件的路径与修改时间（整秒）、输出路径组成，写在 `.yybuild/构建编排/<目标名>.印`。键未变且输出都存在时，该目标报告“已最新”并跳过；依赖目标重建后，其输出的修改时间变化，下游目标的键随之改变。没有输入或输出的目标每次都执行。

## 约束

- 本库只依赖标准库与构建基础（复用其调度器）；命令经标准库的异步子进程启动。
- 标准库没有设置环境变量的接口：需要环境变量时用 `env 名=值 程序 …` 作为命令。
- 修改时间只精确到秒；同一秒内先后改动输入可能被视为未变，需要时用 `--强制`。

# 构建编排

以寻常豫言书构建之目标、所依与诸步，本库并行调度之，据输入跳过已最新者。语言仓之构建目标书于 `应用/豫构/仓库目标。豫`，豫构召本库而行之：于仓根行 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 自举|测试|打包|清理|全部`，或以 `… yy豫构.wasm 目标 名…` 行任一目标。他仓则书一构建程序（可执行之包，如云仓之“云仓构建”），列其诸目标而召 `构建程序主函数`。仓中不复留 shell 之本。

## 用法

```text
寻观「标准库」之书。
寻观「构建编排」之书。

「目标们」乃「列」于「构建目标」也。
「目标们」者
  「列」【
    （「目标」
      于『甲』                           「：名：」
      于『构建 yy甲.wasm』               「：注（--列出 时显之）：」
      于（「罄」授以「字符串」）         「：所依目标之名：」
      于（「列」【（「命令步」于『./yy豫构.wasm』于（「列」【『文件』，『甲。豫』，『--输出』，『yy甲.wasm』】））】）
      于（「列」【（「文件输入」于『甲。豫』）】）
      于（「列」【『yy甲.wasm』】））
  】
也。

「构建程序主函数」于「目标们」。
```

构建程序之命令行：`程序 [目标…] [-j 并发] [--强制] [--不连带] [--列出]`。不举目标则行名“全部”者；`--强制` 不用缓存；`--不连带` 但行所举之目标（所举之间所依仍守其序）；`--列出` 书诸目标及其注。

## 目标与步

`「目标」于 名 于 注 于 所依 于 诸步 于 输入 于 输出`。同目标之步相继而行；异目标所依既成则并行，其上限依 `-j`（默以在线处理器之数）。一步败则止派新步，以非零之码终。

诸步：

- `命令步 程序 参数们`：行外令，参数原样相传，不经 shell。
- `目录内命令步 目录 程序 参数们`：于所定之目行之（启时迁目录，启毕即还）。
- `限时命令步 秒数 程序 参数们`：有 `timeout` 令则限时，逾时即止。
- `函数 注 函数体`：于构建程序中径行一豫言之术；其注入缓存之键。`写文件步 径 文` 本之。
- `复制文件步`、`相同步`（逐字相校）、`建目录步`、`删除步`：常令之简书。
- `独占 组名 步`：同组之步依目标之拓扑序逐一而行，不并发。共一编译缓存之豫构（及内复调豫构之试）必入同组，以守“同缓存同时唯一构建”。

## 缓存

输入为 `文件输入 径` 或 `目录输入 目录 后缀们 所除片段们`（遍而入之，略点起首之名与 `_v0` 之目；后缀空则皆取）。输入输出俱非空者可缓存：键合诸步之述、诸输入之径与修改之时（整秒）、诸输出之径，书于 `.yybuild/构建编排/<目标名>.印`。键不变而输出俱在，则报“已最新”而略之；所依之目标重造，其出之时变，下游之键随改。无输入或无输出者，每次皆行。

## 约束

- 本库唯依标准库与构建基础（用其调度器）；外令以标准库之异步子进程启之。
- 标准库无设环境变量之术：须环境变量，则以 `env 名=值 程序 …` 为令。
- 修改之时唯精于秒；同秒之内先后改输入或视为未变，须时用 `--强制`。