VEP 3: 第三方库与工具规范
VEP 3 — 第三方库与工具规范
摘要
定义 Vix 第三方库和命令行工具（vtool）的项目结构、入口文件与配置规范，确保工具链（包管理器、编译器、运行时）能统一发现和加载第三方项目。
动机
Vix 语言的发展需要健康的第三方生态。统一的项目结构规范可以带来以下好处：
- 包管理器可以自动识别库入口和工具入口，无需额外配置
- 编译器可以快速定位项目的公开 API
- 开发者在不同项目间切换时有一致的认知模型
- 为后续的包注册、版本解析、依赖分析等功能奠定基础
前置依赖
本规范依赖 VEP2（vindex.toml 规范）定义的配置格式。第三方项目必须在其根目录包含 vindex.toml 文件。
详细设计
1. vindex.toml 相关字段
本规范涉及 vindex.toml 中 [project] 表的以下字段：
| 字段 | 适用 | 说明 |
|---|---|---|
name | 库/工具 | 项目名称，须符合包名缩写规则 |
version | 库/工具 | 语义化版本号 |
deps | 库/工具 | 依赖列表 |
entrypoint | 工具 | 工具入口文件路径，相对于项目根目录 |
readme | 库/工具 | 指向帮助文档或说明文件，推荐填写 |
2. 第三方库规范
入口文件：
第三方库的入口文件必须是项目根目录下的 main.vix。这是唯一被认可的库入口，工具链通过此文件加载库的公共 API。
公共 API 边界：
main.vix中 re-export 的所有符号构成该库的公共 API- 未被
main.vix导出（import 后再 export）的符号视为私有，外部不可访问 - 这一约定鼓励库作者显式设计公共接口，避免意外暴露内部实现
示例结构：
库名/
├── vindex.toml
├── main.vix # 库入口，re-export 公共 API
└── src/ # 源码目录
├── module_a.vix
└── module_b.vix
3. vtool 规范
vtool 是用 Vix 编写的命令行工具，可通过包管理器直接安装和调用。
入口文件：
vtool 的入口文件通过 vindex.toml 的 project.entrypoint 字段指定。该字段值为相对于项目根目录的文件路径。此字段对 vtool 为必需项。
帮助信息：
vtool 可通过 project.readme 字段指定帮助文件的位置。当用户在命令行调用 --help 时，工具链可以读取该文件并展示帮助内容。
示例：
[project]
name = "vfmt"
version = "1.0.0"
entrypoint = "src/vfmt.vix"
readme = "README.md"
对应的目录结构：
vfmt/
├── vindex.toml
├── src/
│ └── vfmt.vix # entrypoint 指向此处
└── tests/
4. 目录结构约定
以下为推荐的项目目录布局，工具链可能基于这些约定提供默认行为。
库项目：
库名/
├── vindex.toml
├── main.vix # 库入口
├── src/ # 源码目录
├── tests/ # 测试目录
└── docs/ # 文档（可选）
工具项目：
工具名/
├── vindex.toml
├── src/ # 源码目录
│ └── cli.vix # 推荐入口文件位置
├── tests/ # 测试目录
└── docs/ # 文档（可选）
兼容性考虑
- 本规范仅适用于新建的第三方项目，不追溯已有项目
- 已有项目可通过添加
main.vix或配置entrypoint逐步迁移 main.vix作为强制入口的设计与 VEP2 的entrypoint字段不冲突：库使用main.vix，工具使用entrypoint
未决问题
- 是否需要支持
main.vix之外的库入口名称（如lib.vix），目前保持单一入口策略