|
|
# YAML 配置命名规范指南
|
|
|
|
|
|
## 📋 概述
|
|
|
|
|
|
PHPX 编译器的 YAML 配置文件统一使用**中横线（kebab-case）**命名约定，这符合现代配置文件的行业标准。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎯 命名约定
|
|
|
|
|
|
### ✅ 推荐：中横线（kebab-case）
|
|
|
|
|
|
```yaml
|
|
|
# 所有配置项使用中横线
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
cxx-std: c++17
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
ld-flags:
|
|
|
- -lm
|
|
|
debug: true
|
|
|
no-console: true
|
|
|
```
|
|
|
|
|
|
**优势：**
|
|
|
- ✅ 符合 YAML/JSON 生态标准
|
|
|
- ✅ 与命令行参数一致（`--cxx-std`）
|
|
|
- ✅ Docker、Kubernetes、npm 等主流工具都使用
|
|
|
- ✅ URL 友好，可直接用于 API
|
|
|
|
|
|
---
|
|
|
|
|
|
### ⚠️ 兼容：下划线（snake_case）
|
|
|
|
|
|
为了向后兼容，解析器也支持下划线命名：
|
|
|
|
|
|
```yaml
|
|
|
# 这些也会被正确解析（但不推荐）
|
|
|
type: bin # 等同于 build-mode
|
|
|
cxx_std: c++17 # 等同于 cxx-std
|
|
|
cxxflags: # 等同于 cxx-flags
|
|
|
- -Wall
|
|
|
```
|
|
|
|
|
|
**注意：** 新项目应该使用中横线，下划线仅用于兼容旧配置。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📊 配置项对照表
|
|
|
|
|
|
| 配置项（推荐） | 兼容写法（别名） | 说明 | 类型 |
|
|
|
|--------------|----------------|------|------|
|
|
|
| `name` | - | 项目名称 | string |
|
|
|
| `build-mode` | `type` | 构建模式（bin/ext） | string |
|
|
|
| `version` | - | 版本号 | string |
|
|
|
| `cxx-std` | `cxx_std` | C++ 标准版本 | string |
|
|
|
| `cxx-flags` | `cxxflags` | C++ 编译选项 | array/string |
|
|
|
| `ld-flags` | `ldflags` | 链接器选项 | array/string |
|
|
|
| `sources` | - | 源文件列表 | array |
|
|
|
| `ignore` | - | 忽略的文件/目录 | array |
|
|
|
| `debug` | - | 启用调试模式 | boolean |
|
|
|
| `no-console` | - | 隐藏控制台窗口 | boolean |
|
|
|
|
|
|
**注意：**
|
|
|
- ✅ **推荐使用中横线格式**（如 `build-mode`, `cxx-flags`）
|
|
|
- ⚠️ **别名仅用于向后兼容**（如 `type`, `cxxflags`）
|
|
|
- 📖 **使用手册中的示例可能使用别名**，两者都有效
|
|
|
|
|
|
---
|
|
|
|
|
|
## 💡 完整示例
|
|
|
|
|
|
### 示例 1：基本项目配置
|
|
|
|
|
|
```yaml
|
|
|
# project.yml - 推荐使用中横线
|
|
|
name: hello-world
|
|
|
build-mode: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx-std: c++17
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
- -O2
|
|
|
|
|
|
sources:
|
|
|
- src/main.php
|
|
|
- src/utils.php
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 示例 2：扩展模块配置
|
|
|
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
name: my-extension
|
|
|
build-mode: ext
|
|
|
version: 0.1.0
|
|
|
|
|
|
cxx-std: c++17
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -fPIC
|
|
|
|
|
|
ld-flags:
|
|
|
- -shared
|
|
|
|
|
|
sources:
|
|
|
- src/*.php
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 示例 3：复杂项目配置
|
|
|
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
version: 2.0.0
|
|
|
|
|
|
# C++ 标准
|
|
|
cxx-std: c++20
|
|
|
|
|
|
# 编译选项
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
- -Wpedantic
|
|
|
- -O3
|
|
|
|
|
|
# 链接选项
|
|
|
ld-flags:
|
|
|
- -lm
|
|
|
- -lpthread
|
|
|
- -lssl
|
|
|
|
|
|
# 源文件
|
|
|
sources:
|
|
|
- src/main.php
|
|
|
- src/controllers
|
|
|
- src/models
|
|
|
- src/views
|
|
|
|
|
|
# 忽略的文件
|
|
|
ignore:
|
|
|
- tests/
|
|
|
- docs/
|
|
|
- "*.md"
|
|
|
- ext-json # 忽略内置扩展
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔧 优先级规则
|
|
|
|
|
|
配置值的读取遵循以下优先级（从高到低）：
|
|
|
|
|
|
1. **命令行参数**（最高优先级）
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++20
|
|
|
```
|
|
|
|
|
|
2. **YAML 配置文件**
|
|
|
```yaml
|
|
|
cxx-std: c++17
|
|
|
```
|
|
|
|
|
|
3. **平台默认值**
|
|
|
- Windows: `c++17`
|
|
|
- Unix: `c++14`
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔄 兼容性说明
|
|
|
|
|
|
### 自动转换逻辑
|
|
|
|
|
|
解析器会自动处理以下情况：
|
|
|
|
|
|
```php
|
|
|
// Translator.php 中的逻辑
|
|
|
|
|
|
// build-mode / type 别名支持
|
|
|
$buildMode = $cfg['build-mode'] ?? $cfg['type'] ?? null;
|
|
|
if (!empty($buildMode)) {
|
|
|
$this->setBuildMode($buildMode);
|
|
|
}
|
|
|
|
|
|
// cxx-flags / cxxflags 别名支持
|
|
|
$cxxflags = $cfg['cxx-flags'] ?? $cfg['cxxflags'] ?? null;
|
|
|
if (!empty($cxxflags)) {
|
|
|
// 处理 cxxflags
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**支持的写法：**
|
|
|
```yaml
|
|
|
# ✅ 推荐（中横线）
|
|
|
build-mode: bin
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
|
|
|
# ⚠️ 兼容（别名，用于向后兼容使用手册）
|
|
|
type: bin
|
|
|
cxxflags:
|
|
|
- -Wall
|
|
|
|
|
|
# 两者效果完全相同
|
|
|
```
|
|
|
|
|
|
**优先级：**
|
|
|
1. 如果同时指定了 `build-mode` 和 `type`，优先使用 `build-mode`
|
|
|
2. 如果同时指定了 `cxx-flags` 和 `cxxflags`，优先使用 `cxx-flags`
|
|
|
3. 建议只使用其中一种，避免混淆
|
|
|
|
|
|
---
|
|
|
|
|
|
### 废弃的写法
|
|
|
|
|
|
以下写法仍然有效，但**不推荐**：
|
|
|
|
|
|
```yaml
|
|
|
# ❌ 不推荐：在 cxx-flags 中包含 -std=
|
|
|
cxx-flags:
|
|
|
- -std=c++17 # 应该使用 cxx-std
|
|
|
- -Wall
|
|
|
|
|
|
# ✅ 推荐：分开配置
|
|
|
cxx-std: c++17
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📝 迁移指南
|
|
|
|
|
|
### 从旧配置迁移到新配置
|
|
|
|
|
|
#### ⚠️ 旧配置（使用手册中的示例，仍然有效）
|
|
|
|
|
|
```yaml
|
|
|
name: my-app
|
|
|
type: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx_std: c++14
|
|
|
|
|
|
cxxflags: |
|
|
|
-std=c++14
|
|
|
-Wall
|
|
|
-O2
|
|
|
|
|
|
ldflags: -lm -lpthread
|
|
|
```
|
|
|
|
|
|
**说明：**
|
|
|
- ✅ `type` 是 `build-mode` 的别名（向后兼容）
|
|
|
- ✅ `cxxflags` 是 `cxx-flags` 的别名（向后兼容）
|
|
|
- ✅ 这些配置**仍然完全有效**
|
|
|
- 📖 使用手册中的示例继续使用这些别名
|
|
|
|
|
|
---
|
|
|
|
|
|
#### ✅ 新配置（推荐）
|
|
|
|
|
|
```yaml
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx-std: c++14
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -O2
|
|
|
|
|
|
ld-flags:
|
|
|
- -lm
|
|
|
- -lpthread
|
|
|
```
|
|
|
|
|
|
**改进点：**
|
|
|
1. ✅ `type` → `build-mode`（更清晰的中横线命名）
|
|
|
2. ✅ `cxx_std` → `cxx-std`（中横线）
|
|
|
3. ✅ `cxxflags` → `cxx-flags`（中横线）
|
|
|
4. ✅ 移除 `-std=c++14`（使用独立的 `cxx-std`）
|
|
|
5. ✅ 数组格式更清晰
|
|
|
|
|
|
---
|
|
|
|
|
|
### 重要提示
|
|
|
|
|
|
**不需要立即迁移！**
|
|
|
|
|
|
- ✅ 旧配置（使用 `type`, `cxxflags`）**完全有效**
|
|
|
- ✅ 新配置（使用 `build-mode`, `cxx-flags`）**推荐使用**
|
|
|
- ✅ 两者可以混合使用（但不建议）
|
|
|
- 📖 使用手册中的示例保持不变
|
|
|
|
|
|
**建议：**
|
|
|
- 新项目 → 使用中横线格式
|
|
|
- 现有项目 → 可以继续使用别名，无需修改
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎨 最佳实践
|
|
|
|
|
|
### 1. 始终使用中横线
|
|
|
|
|
|
```yaml
|
|
|
# ✅ 好
|
|
|
cxx-std: c++17
|
|
|
build-mode: bin
|
|
|
debug: true
|
|
|
|
|
|
# ❌ 避免
|
|
|
cxx_std: c++17
|
|
|
build_mode: bin
|
|
|
debug_info: true
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2. 使用数组而非多行字符串
|
|
|
|
|
|
```yaml
|
|
|
# ✅ 推荐：数组格式
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
- -O2
|
|
|
|
|
|
# ⚠️ 可用但不推荐：多行字符串
|
|
|
cxx-flags: |
|
|
|
-Wall
|
|
|
-Wextra
|
|
|
-O2
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 3. 分离 C++ 标准和编译选项
|
|
|
|
|
|
```yaml
|
|
|
# ✅ 推荐
|
|
|
cxx-std: c++17
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -O2
|
|
|
|
|
|
# ❌ 避免
|
|
|
cxx-flags:
|
|
|
- -std=c++17 # 不要在这里指定标准
|
|
|
- -Wall
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4. 添加注释说明
|
|
|
|
|
|
```yaml
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
|
|
|
# 使用 C++17 以获得更好的性能
|
|
|
cxx-std: c++17
|
|
|
|
|
|
# 启用所有警告
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
- -Wpedantic
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🐛 常见问题
|
|
|
|
|
|
### Q1: 我可以使用 `type` 和 `cxxflags` 吗？
|
|
|
|
|
|
A: **可以！** 这些是官方支持的别名，用于向后兼容使用手册。
|
|
|
|
|
|
```yaml
|
|
|
# ✅ 完全有效（使用手册中的示例）
|
|
|
type: bin
|
|
|
cxxflags:
|
|
|
- -Wall
|
|
|
|
|
|
# ✅ 同样有效（推荐的新格式）
|
|
|
build-mode: bin
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
```
|
|
|
|
|
|
**建议：**
|
|
|
- 新项目 → 使用中横线格式
|
|
|
- 现有项目 → 可以继续使用别名
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q2: `type` 和 `build-mode` 有什么区别？
|
|
|
|
|
|
A: **没有区别**，`type` 是 `build-mode` 的别名。推荐使用 `build-mode`。
|
|
|
|
|
|
```yaml
|
|
|
# 这两个是等价的
|
|
|
build-mode: bin # ✅ 推荐
|
|
|
type: bin # ⚠️ 别名（使用手册中的示例）
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q3: 可以在 cxx-flags 中使用 `-std=` 吗？
|
|
|
|
|
|
A: 技术上可以，但**不推荐**。应该使用独立的 `cxx-std` 配置项。
|
|
|
|
|
|
```yaml
|
|
|
# ❌ 不推荐
|
|
|
cxx-flags:
|
|
|
- -std=c++17
|
|
|
- -Wall
|
|
|
|
|
|
# ✅ 推荐
|
|
|
cxx-std: c++17
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q4: 如何覆盖配置文件中的设置？
|
|
|
|
|
|
A: 使用命令行参数：
|
|
|
|
|
|
```bash
|
|
|
# 覆盖 cxx-std
|
|
|
php bin/compiler.php project.yml --cxx-std=c++20
|
|
|
|
|
|
# 覆盖 build-mode
|
|
|
php bin/compiler.php project.yml --mode=ext
|
|
|
|
|
|
# 启用调试信息
|
|
|
php bin/compiler.php project.yml --debug
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📚 相关资源
|
|
|
|
|
|
- [YAML 官方规范](https://yaml.org/spec/)
|
|
|
- [Kubernetes 命名约定](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/)
|
|
|
- [Docker Compose 文件参考](https://docs.docker.com/compose/compose-file/)
|
|
|
- [npm package.json 规范](https://docs.npmjs.com/cli/v9/configuring-npm/package-json)
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎉 总结
|
|
|
|
|
|
### 核心原则
|
|
|
|
|
|
1. ✅ **统一使用中横线**（kebab-case）
|
|
|
2. ✅ **分离关注点**（`cxx-std` vs `cxx-flags`）
|
|
|
3. ✅ **使用数组格式**（更易读）
|
|
|
4. ✅ **添加注释**（提高可维护性）
|
|
|
5. ✅ **保持向后兼容**（支持 `type`, `cxxflags` 别名）
|
|
|
|
|
|
### 别名说明
|
|
|
|
|
|
**为了兼容使用手册，以下别名仍然有效：**
|
|
|
|
|
|
| 推荐写法 | 别名（使用手册） | 状态 |
|
|
|
|---------|----------------|------|
|
|
|
| `build-mode` | `type` | ✅ 完全支持 |
|
|
|
| `cxx-flags` | `cxxflags` | ✅ 完全支持 |
|
|
|
|
|
|
**建议：**
|
|
|
- 📖 使用手册中的示例继续使用别名
|
|
|
- ✨ 新项目推荐使用中横线格式
|
|
|
- 🔄 现有项目无需修改，别名完全有效
|
|
|
|
|
|
### 快速参考
|
|
|
|
|
|
```yaml
|
|
|
# 标准模板（推荐）
|
|
|
name: my-project
|
|
|
build-mode: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx-std: c++17
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
|
|
|
ld-flags:
|
|
|
- -lm
|
|
|
|
|
|
sources:
|
|
|
- src/*.php
|
|
|
```
|
|
|
|
|
|
```yaml
|
|
|
# 使用手册中的示例（仍然有效）
|
|
|
name: my-project
|
|
|
type: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx_std: c++17
|
|
|
|
|
|
cxxflags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
|
|
|
ldflags:
|
|
|
- -lm
|
|
|
|
|
|
sources:
|
|
|
- src/*.php
|
|
|
```
|
|
|
|
|
|
遵循这些规范，您的配置文件将更加清晰、易读和易于维护！
|
|
|
|
