ESSO

ESSO-10498

ETNSBuild 多语言构建系统核心接口标准

ESSO-10498 — ETNSBuild Multi-Language Build System: Core Interface Standard

版本：1.0.0 状态：启用 发布机构：Ethernos Studio - System Labs 规范编号：ESSO-10498 适用范围：.CAT Framework ETNSBuild或其他实现 最后更新：2026-07-09

---

修订记录

版本	日期	修订内容	作者
2026.1-draft	2026-07-09	初始草案，与 ESSO-10499 同步发布	Kimi k2.6-Thinking
1.0.0	2026-07-09	添加元信息、修正规范性引用文件	dhjs0000

---

目录

1. 范围
2. 规范性引用文件
3. 术语和定义
4. 系统架构
5. 构建生命周期
6. 构建图（Build Graph）模型
7. 工具链抽象接口（TAI）
8. 制品指纹与缓存
9. 并发执行模型
10. 与 ESSO-10499 的集成接口
11. 扩展与插件机制 附录 A：工具链描述符示例 附录 B：构建图 JSON 交换格式（仅供调试）

---

1. 范围

本标准规定 ETNSBuild 多语言构建系统的核心运行时接口、构建生命周期阶段、工具链抽象层、制品指纹算法及缓存协议。

本标准适用于：

• ETNSBuild 主程序（etns 命令行接口）；
• 第三方工具链适配器（Toolchain Adapter）开发者；
• ESSO-10499 兼容的包管理器与项目索引系统。

---

2. 规范性引用文件

• SPDX License List 3.25
• SemVer 2.0.0
• ESSO-10499 — Ethernos 通用程序设计项目管理系统的包信息与索引文件标准（配套）

---

3. 术语和定义

术语	定义
Driver	ETNSBuild 主入口，负责解析命令行参数、加载 Manifest、调度生命周期。
Planner	构建图生成器，将 ESSO-10499 描述的 [index] 与 [build] 转换为有向无环图（DAG）。
Executor	构建图执行器，按拓扑序调度编译/链接任务，管理进程池。
Cache	制品缓存子系统，基于内容寻址存储（CAS）实现增量构建。
Artifact	构建过程中的中间或最终产物，如 .o、.a、.exe、.cayc 字节码。
Fingerprint	制品的唯一内容标识，默认采用 BLAKE3-256。
Toolchain Adapter	工具链适配器，将 ETNSBuild 通用构建指令翻译为具体编译器调用（如 cayc、clang++、rustc）。
Stage	构建生命周期中的独立阶段，阶段间通过显式数据依赖连接。

---

4. 系统架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Driver    │────▶│   Planner   │────▶│  Executor   │
│  (etns)     │     │  (DAG Gen)  │     │ (Process    │
└─────────────┘     └─────────────┘     │   Pool)     │
                                          └──────┬──────┘
                                                 │
                                          ┌──────▼──────┐
                                          │    Cache    │
                                          │  (BLAKE3)   │
                                          └─────────────┘
                                                 │
                                          ┌──────▼──────┐
                                          │  Toolchain  │
                                          │  Adapters   │
                                          │(cavvy/cpp/…)│
                                          └─────────────┘

---

5. 构建生命周期

ETNSBuild 将一次完整构建划分为以下不可跳过的阶段（除非显式 --skip）：

阶段	标识	输入	输出	说明
Init	INIT	命令行参数	内存配置	解析 .epm、.epi、.epl
Configure	CFG	Manifest + 环境变量	构建配置表	解析条件依赖、选择工具链
Resolve	RES	依赖声明 + Lock 文件	依赖图 + 源码树	下载/校验外部依赖
Compile	CPL	源文件 + 头文件	目标文件/字节码	调用工具链适配器
Link	LNK	目标文件 + 库	可执行文件/库	链接器调用
Test	TST	测试清单	测试报告	可选，由 --test 触发
Install	INS	最终制品	安装目录	由 --install 或 install 子命令触发

阶段契约：每个阶段必须产生明确的输出指纹集合，供下一阶段作为输入指纹校验。若输入指纹未变，阶段可标记为 CACHED。

---

6. 构建图（Build Graph）模型

6.1 图结构

构建图 G = (V, E) 为严格有向无环图（DAG）：

• 节点 v ∈ V：表示一个构建任务（Task），携带：
  • task_id：全局唯一标识（{package_name}:{target}:{stage}:{hash}）
  • inputs：输入文件指纹列表
  • outputs：输出文件路径列表
  • command：待执行的 shell 命令或适配器调用
  • env：环境变量覆盖表
• 边 e ∈ E：表示数据依赖，Planner 必须保证无环。

6.2 任务类型

类型	标识	说明
compile	C	单源文件到目标文件
link	L	多目标文件到最终制品
custom	X	用户自定义脚本（[build.scripts]）
meta	M	不产生产物的信息聚合任务

---

7. 工具链抽象接口（TAI）

Toolchain Adapter 必须实现以下接口（以伪代码描述）：

struct ToolchainAdapter {
    // 身份
    string name;           // "cavvy-llvm", "gcc-14", "msvc-2022"
    string version;        // 适配器版本，非编译器版本
    string[] supported_langs;  // ["cavvy", "cpp"]

    // 能力探测
    bool probe();          // 检测编译器是否在 PATH 中可用

    // 编译
    Command compile(
        SourceFile src,
        HeaderDeps deps,
        CompileFlags flags,
        OutputPath out
    );

    // 链接
    Command link(
        ObjectFile[] objs,
        Library[] libs,
        LinkFlags flags,
        OutputPath out,
        TargetType type  // executable | static | dynamic
    );

    // 依赖扫描
    string[] scan_headers(SourceFile src);  // 返回该文件直接依赖的头文件路径
};

7.1 工具链描述符

工具链描述符存放于 $ESSO_CACHE/toolchains/{name}.etns-toolchain：

# gcc-14.etns-toolchain
[toolchain]
name = "gcc-14"
version = "14.2.0"
langs = ["c", "cpp"]

[toolchain.paths]
cc = "/usr/bin/gcc"
cxx = "/usr/bin/g++"
ld = "/usr/bin/ld"
ar = "/usr/bin/ar"

[toolchain.defaults]
std_c = "c17"
std_cpp = "c++23"

---

8. 制品指纹与缓存

8.1 指纹算法

• 默认：BLAKE3-256
• 回退：SHA3-256（当平台不支持 BLAKE3 时）
• 输入指纹：对文件内容计算哈希；对命令行，将命令字符串按 UTF-8 编码后哈希。

8.2 缓存键

CacheKey = BLAKE3(
    "ETNSBuild" || version || 
    toolchain_name || toolchain_version ||
    task_type || 
    sorted_input_fingerprints ||
    command_string ||
    env_fingerprint
)

8.3 缓存目录结构

$ESSO_CACHE/
├── artifacts/
│   └── ab/cd/abcdef1234...  # 内容寻址，前 2 字节作为目录分片
├── manifests/
│   └── {package_name}-{version}.lock
└── toolchains/
    └── *.etns-toolchain

---

9. 并发执行模型

9.1 进程池

Executor 维护一个进程池，默认并发度为 min(物理核心数, 16)，可通过 -j 覆盖。

9.2 调度规则

1. 按拓扑序调度，无依赖的任务可并行；
2. 同一目标文件的 compile 与 link 必须串行；
3. 自定义脚本（X 类型）默认串行，除非标记 parallel = true；
4. 网络下载任务（RES 阶段）独立线程池，不占用编译进程池。

---

10. 与 ESSO-10499 的集成接口

10.1 Manifest 加载

Driver 按以下顺序定位 Manifest：

1. 显式 -f /path/to/Package.epm；
2. 当前目录 ./Package.epm；
3. 当前目录 ./ESSO-MANIFEST.epm；
4. 当前目录 ./Package.epm + ./Index.epi（分离模式）。

10.2 字段映射

ESSO-10499 字段	ETNSBuild 内部表示
[package].name	Project.name
[package].version	Project.version
[index].src	BuildGraph.source_nodes
[build].entry	BuildGraph.entry_node
[dependencies].*	Resolver.dependency_graph
[build.flags]	ToolchainAdapter.flags_override

10.3 错误码

ETNSBuild 在解析 ESSO-10499 文件时，必须产生以下标准化错误码：

错误码	场景	级别
E10499-001	Manifest 文件缺失	Fatal
E10499-002	[package].name 包含非法字符	Fatal
E10499-003	[package].version 不符合 SemVer	Fatal
E10499-004	[index].src 引用不存在的文件	Fatal
E10499-005	.epm 与 .epi 的 [index] 节冲突	Warn
E10499-006	依赖版本无法解析（无匹配版本）	Fatal
E10499-007	工具链探测失败（probe() 返回 false）	Fatal

---

11. 扩展与插件机制

11.1 内置插件

ETNSBuild 内置以下语言插件，无需额外配置：

• cavvy：调用 cayc；
• cpp / c：调用系统工具链（gcc、clang、msvc）；
• rust：调用 rustc 或 cargo（作为外部命令）。

11.2 外部插件

外部插件以动态库形式存放于 $ESSO_CACHE/plugins/：

plugins/
├── libetns-cavvy-ffi.so      # Cavvy FFI 辅助构建插件
├── libetns-wasm-pack.so      # WebAssembly 打包插件
└── ...

插件必须导出符号：

int etns_plugin_init(PluginRegistry* reg);

---

附录 A：工具链描述符示例

# cayc-5.3.etns-toolchain
[toolchain]
name = "cavvy-llvm"
version = "5.3.0"
langs = ["cavvy"]

[toolchain.paths]
compiler = "cayc"
linker = "lld"
assembler = "llc"

[toolchain.defaults]
std = "5.3"
target = "x86_64-pc-linux-gnu"

[toolchain.capabilities]
lto = true
cross_compile = true
simd = ["sse4.2", "avx2", "neon"]

---

附录 B：构建图 JSON 交换格式（仅供调试）

{
    "version": "ESSO-10498/2026.1",
    "tasks": [
        {
            "id": "cavvy-ffi-demo:main:CPL:a1b2c3",
            "type": "compile",
            "inputs": ["src/main.cay"],
            "outputs": ["build/main.o"],
            "command": "cayc -O3 src/main.cay -o build/main.o",
            "deps": []
        },
        {
            "id": "cavvy-ffi-demo:ffi-demo:LNK:d4e5f6",
            "type": "link",
            "inputs": ["build/main.o", "build/vector_bridge.o"],
            "outputs": ["build/ffi-demo"],
            "command": "lld build/main.o build/vector_bridge.o -o build/ffi-demo",
            "deps": ["cavvy-ffi-demo:main:CPL:a1b2c3"]
        }
    ]
}

---

dhjs0000 ESSO 标准化与规范组织（ESSO） 本标准最终解释权归 ESSO 技术委员会所有。

This site is open source. Improve this page.