ESSO

ESSO-10499

Ethernos通用程序设计项目管理系统的包信息与索引文件标准

ESSO-10499 — Ethernos Universal Program Design Project Management System: Package Information and Index File Standard

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

---

修订记录

版本	日期	修订内容	作者
2026.1-draft	2026-07-09	初始草案	Kimi k2.6-Thinking
2026.1-draft.2	2026-07-09	修正规范性引用文件	Kimi k2.6-Thinking
1.0.0	2026-07-09	添加元信息头	dhjs0000

---

目录

1. 范围
2. 规范性引用文件
3. 术语和定义
4. 文件体系架构
5. EPML 语法规范
6. 包信息模型 [package]
7. 索引文件模型 [index]
8. 依赖解析模型 [dependencies]
9. 构建描述模型 [build]
10. 多语言适配规则
11. 验证与合规 附录 A：Cavvy 项目完整示例 附录 B：C++ 项目完整示例 附录 C：EPML BNF 语法摘要

---

1. 范围

本标准规定 Ethernos 技术生态下通用程序设计项目（包括但不限于 Cavvy、Vix、C/C++、Rust、C# 等）的包信息描述格式、源文件索引规范、依赖解析规则及构建元数据结构。

本标准适用于：

• ETNSBuild 多语言构建系统；
• ESSO 兼容的包管理器与仓库索引；
• 任何需要跨语言、跨平台声明项目元数据的场景。

本标准不采用 JSON 格式，也不使用 package.json 作为文件名。

2. 规范性引用文件

• ESSO-10498 — ETNSBuild 多语言构建系统核心接口标准
• SPDX License List 3.25
• SemVer 2.0.0

3. 术语和定义

术语	定义
EPML	Ethernos Project Manifest Language，本标准定义的声明式配置语言。
Manifest	包信息主文件，描述项目身份、版本、作者、许可证等元数据。
Index	索引文件，描述项目内源文件、头文件、资源文件及模块边界。
Lock	锁文件，记录依赖解析后的精确版本与校验和，确保可复现构建。
Target	构建产物类型，如 executable、static-library、dynamic-library、module。
Toolchain	构建工具链标识，如 cavvy-llvm、gcc-14、msvc-2022。

---

4. 文件体系架构

每个符合本标准的项目根目录必须包含以下文件之一：

文件角色	文件名	扩展名	是否必需	说明
包信息主文件	ESSO-MANIFEST 或 Package	.epm	是	项目身份与依赖声明
源文件索引	ESSO-INDEX 或 Index	.epi	条件必需	当 [index] 未内联于 .epm 时必需
依赖锁文件	ESSO-LOCK 或 Package	.epl	否	自动生成，禁止手动编辑

合并规则：若 .epm 文件中包含 [index] 节，则无需单独的 .epi 文件；若两者同时存在，以 .epi 为准，构建系统须发出 WARN_INDEX_SHADOW 警告。

---

5. EPML 语法规范

5.1 基础规则

• 编码：UTF-8，无 BOM。
• 换行：\n（LF）；允许 \r\n（CRLF），但工具链写入时必须使用 LF。
• 注释：# 或 // 引导至行尾；多行注释不支持。
• 标识符：[A-Za-z_][A-Za-z0-9_-]*。
• 路径：统一使用正斜杠 /；以 ./ 开头的路径为相对路径，以 / 或盘符开头的路径为绝对路径（不推荐纳入版本控制）。

5.2 类型系统

类型	字面量示例	说明
string	"hello" 或 """multi\nline"""	支持转义序列 \n, \t, \\, \"
int	42, -7, 0x2A	十进制或十六进制
float	3.14, -0.5	IEEE-754 双精度
bool	true, false	小写
array	[1, 2, 3]	同类型元素，尾随逗号可选
table	{ key = "val" }	键值对集合，用于内联子结构
semver	"5.3.0"	符合 SemVer 2.0.0 的字符串，解析时校验
spdx	"AGPL-3.0"	SPDX 许可证标识符

5.3 节（Section）

节使用方括号声明，支持点分层级：

[package]
name = "my-project"

[package.authors]
primary = "dhjs0000"
email = "[email protected]"

[build.flags]
cavvy = ["-O3", "--lto"]

---

6. 包信息模型 [package]

字段	类型	必需	说明
name	string	是	项目全局唯一名，符合 ESSO 包命名规范（小写，连字符分隔）
version	semver	是	项目版本号，遵循 SemVer
edition	string	否	语言/平台版本，如 "2026", "c++23", "cavvy-5.3"
description	string	否	项目简介，不超过 256 字符
authors	array 或 table	否	作者列表
license	spdx	是	主许可证；多许可证使用 licenses = ["MIT", "Apache-2.0"]
repository	string	否	源码仓库 URL
homepage	string	否	项目主页
keywords	array	否	关键词，用于仓库检索
categories	array	否	ESSO 分类标签，如 ["system-tools", "compiler"]

6.1 作者结构

[package.authors]
list = [
    { name = "dhjs0000", email = "[email protected]", role = "maintainer" },
    { name = "ywhdzrb", role = "contributor" }
]

---

7. 索引文件模型 [index]

索引用于精确描述项目源文件构成，替代传统通配符（如 *.c），确保可复现构建。

字段	类型	必需	说明
src	array	是	主源文件路径列表
headers	array	否	公开头文件/接口定义路径
private_headers	array	否	内部头文件，不纳入导出
resources	array	否	非代码资源（图片、配置、着色器等）
modules	array	否	模块描述表（见 7.1）
exclude	array	否	显式排除路径，优先级高于 src 通配

7.1 模块边界（Cavvy / C++20 Modules）

[index.modules]
list = [
    {
        name = "std.vector",
        interface = "src/std/vector.cay",
        implementation = "src/std/vector_impl.cay",
        dependencies = ["std.memory", "std.iterator"]
    }
]

7.2 路径宏

宏	展开值
$PROJECT_ROOT	项目根目录（.epm 所在目录）
$BUILD_DIR	构建输出目录
$ESSO_CACHE	ETNSBuild 全局缓存目录

---

8. 依赖解析模型 [dependencies]

依赖支持多种来源，构建系统必须按以下优先级解析：

1. Builtin：ETNSBuild 内置标准库；
2. Registry：ESSO 中央仓库或私有 registry；
3. Git：Git 仓库，支持 branch, tag, rev；
4. Path：本地文件系统路径，用于工作区（workspace）开发；
5. System：系统包管理器（如 apt, pacman, vcpkg），仅作元数据提示。

8.1 依赖声明语法

[dependencies]
# 1. Registry 依赖（最常用）
"std.vector" = "5.3.0"                    # 简写，默认 registry
"ethernos.net" = { version = ">=2.1.0, <3.0.0", registry = "esso-main" }

# 2. Git 依赖
"libffi" = { git = "https://github.com/ethernos/libffi", tag = "v3.4.6" }

# 3. Path 依赖（工作区）
"internal.tool" = { path = "../tools/etns-codegen" }

# 4. System 依赖（仅提示，不管理）
"openssl" = { system = "openssl-dev", optional = true }

# 5. 条件依赖
[dependencies.target.'cfg(os = "linux")']
"libx11" = "1.8.0"

8.2 依赖特征（Features）

[dependencies."std.vector"]
version = "5.3.0"
default-features = false
features = ["allocator-api", "simd"]

---

9. 构建描述模型 [build]

字段	类型	必需	说明
type	string	是	executable, static-library, dynamic-library, module, header-only
toolchain	string	否	默认由 ETNSBuild 推断
entry	string	条件必需	可执行文件入口；type = "executable" 时必需
out_dir	string	否	输出目录，默认 $PROJECT_ROOT/build
out_name	string	否	输出文件名（不含扩展名），默认等于 package.name
flags	table	否	按工具链/语言分发的编译标志
defines	array	否	预处理器宏定义，如 ["DEBUG", "VERSION=1"]
links	array	否	链接库名称，如 ["pthread", "dl"]
link_dirs	array	否	额外库搜索路径
std	string	否	语言标准，如 "c++23", "c17", "cavvy-5.3"

9.1 工具链标志分发

[build.flags]
cavvy = ["-O3", "--lto", "--target=x86_64-pc-windows-gnu"]
cpp = ["-std=c++23", "-Wall", "-Wextra", "-Werror"]
linker = ["-fuse-ld=lld", "--strip-all"]

9.2 构建脚本钩子

[build.scripts]
pre-configure = "./scripts/check-llvm.sh"
pre-build = "etns codegen --target $BUILD_DIR"
post-build = ["strip $BUILD_DIR/$OUT_NAME", "etns test --all"]

---

10. 多语言适配规则

ETNSBuild 读取 .epm 后，根据 [language] 或 [build] 中的 type 字段触发语言适配层。

10.1 语言识别表

language.type	适配目标	默认 build.type 推断	标准文件扩展名
cavvy	Cavvy 编译器 (cayc)	executable	.cay
vix	Vix 编译器 (vixc)	executable	.vix
cpp / c++	C++ 工具链	executable	.cpp, .hpp, .h
c	C 工具链	executable	.c, .h
rust	rustc / cargo	executable	.rs
csharp / c#	dotnet / csc	executable	.cs

10.2 跨语言 FFI 项目

对于 Cavvy FFI 调用 C++ 模板等场景，需在 [build] 中显式声明辅助语言：

[build]
type = "executable"
language = "cavvy"

[build.ffi]
lang = "cpp"
headers = ["include/bridge.hpp"]
static_libs = ["build/native/libbridge.a"]

---

11. 验证与合规

11.1 必需校验项

1. package.name 必须全局唯一（在 registry 范围内）；
2. package.version 必须符合 SemVer；
3. package.license 必须是有效 SPDX 标识符；
4. [index].src 不能为空数组；
5. 所有 path 依赖必须指向项目根目录的相对路径；
6. build.entry 必须存在于 [index].src 或 [index].headers 中。

11.2 警告项

警告码	场景
WARN_INDEX_SHADOW	.epm 与 .epi 同时存在且 [index] 节冲突
WARN_UNUSED_DEP	[dependencies] 中声明的依赖未在 [index] 中被引用
WARN_ABS_PATH	使用了绝对路径，可能导致构建不可移植

---

附录 A：Cavvy 项目完整示例

# Package.epm
# ESSO-10499  compliant manifest for a Cavvy project

[package]
name = "cavvy-ffi-demo"
version = "0.4.8"
edition = "2026"
description = "Cavvy FFI milestone: std::vector interop"
authors = [
    { name = "dhjs0000", email = "[email protected]" }
]
license = "AGPL-3.0"
repository = "https://github.com/ethernos/cavvy-ffi-demo"
keywords = ["cavvy", "ffi", "vector", "interop"]
categories = ["dev-tools", "language-binding"]

[language]
type = "cavvy"
std = "5.3"

[index]
src = [
    "src/main.cay",
    "src/vector_bridge.cay"
]
headers = [
    "include/vector_c_api.h"
]
resources = []

[index.modules]
list = [
    {
        name = "std.vector",
        interface = "src/std/vector.cay",
        dependencies = ["std.memory"]
    }
]

[dependencies]
"std.memory" = { version = "5.3.0", source = "builtin" }
"libbridge" = { path = "../libbridge", optional = false }

[build]
type = "executable"
entry = "src/main.cay"
out_dir = "build"
out_name = "ffi-demo"

[build.flags]
cavvy = ["-O3", "--lto=thin"]
linker = ["-fuse-ld=lld"]

[build.ffi]
lang = "cpp"
headers = ["include/bridge.hpp"]
static_libs = ["build/native/libbridge.a"]

[scripts]
test = "etns test --target x86_64-unknown-linux-gnu"

---

附录 B：C++ 项目完整示例

# Package.epm
# A modern C++23 project using ETNSBuild

[package]
name = "etns-core"
version = "2.1.0"
edition = "c++23"
description = "ETNSBuild core runtime"
license = "BSD-3-Clause"

[language]
type = "cpp"

[index]
src = [
    "src/main.cpp",
    "src/build_system.cpp",
    "src/package_manifest.cpp"
]
headers = [
    "include/etns/build_system.hpp",
    "include/etns/manifest.hpp"
]
private_headers = [
    "src/detail/parser.hpp"
]

[dependencies]
"fmt" = { version = "10.2.0", registry = "esso-cpp" }
"tomlplusplus" = { git = "https://github.com/marzer/tomlplusplus", tag = "v3.4.0" }

[build]
type = "executable"
entry = "src/main.cpp"
out_dir = "build"

[build.flags]
cpp = ["-std=c++23", "-Wall", "-Wextra", "-Wpedantic", "-O3"]
linker = ["-pthread", "-fuse-ld=lld"]

[build.defines]
macros = ["ETNS_VERSION_MAJOR=2", "ETNS_VERSION_MINOR=1"]

---

附录 C：EPML BNF 语法摘要

document     ::= section*
section      ::= '[' key_path ']' EOL pair*
key_path     ::= ident ('.' ident)*
pair         ::= ident '=' value EOL
value        ::= scalar | array | table
scalar       ::= string | int | float | bool | path
string       ::= '"' char* '"' | '"""' char* '"""'
int          ::= ['-'] digit+ | '0x' hex_digit+
float        ::= ['-'] digit+ '.' digit+
bool         ::= 'true' | 'false'
path         ::= string  ; -- 语义层面校验路径格式
array        ::= '[' [value (',' value)*] ']'
table        ::= '{' [pair (',' pair)*] '}'
ident        ::= [A-Za-z_] [A-Za-z0-9_-]*
EOL          ::= '\n' | '\r\n'
comment      ::= '#' | '//'

---

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

This site is open source. Improve this page.