|
|
# 配置优先级规则说明
|
|
|
|
|
|
## 📋 概述
|
|
|
|
|
|
PHPX 编译器的配置遵循明确的优先级规则，确保用户可以灵活地控制编译行为。
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎯 优先级顺序（从高到低）
|
|
|
|
|
|
```
|
|
|
1. 命令行参数（最高优先级）
|
|
|
↓
|
|
|
2. YAML 配置文件
|
|
|
↓
|
|
|
3. 平台默认值（最低优先级）
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 💡 工作原理
|
|
|
|
|
|
### 执行流程
|
|
|
|
|
|
```mermaid
|
|
|
graph TD
|
|
|
A[启动编译器] --> B[解析命令行参数]
|
|
|
B --> C{输入类型?}
|
|
|
C -->|YAML 文件| D[解析 YAML 配置]
|
|
|
C -->|单 PHP 文件| E[跳过 YAML]
|
|
|
C -->|目录| F[跳过 YAML]
|
|
|
D --> G[应用命令行参数覆盖]
|
|
|
E --> G
|
|
|
F --> G
|
|
|
G --> H[开始编译]
|
|
|
```
|
|
|
|
|
|
### 详细说明
|
|
|
|
|
|
1. **构造函数阶段**
|
|
|
- 解析命令行参数
|
|
|
- **不立即应用**到属性
|
|
|
- 仅处理 `--help` 和 `--version`
|
|
|
|
|
|
2. **YAML 解析阶段**（仅当输入是 `.yml` 文件时）
|
|
|
- 读取 `project.yml` 配置
|
|
|
- 应用到编译器属性
|
|
|
- 设置默认值
|
|
|
|
|
|
3. **命令行参数应用阶段**
|
|
|
- 检查哪些命令行参数被定义
|
|
|
- **覆盖** YAML 配置或默认值
|
|
|
- 确保命令行参数优先级最高
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📊 配置项示例
|
|
|
|
|
|
### 示例 1：C++ 标准版本
|
|
|
|
|
|
#### YAML 配置
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
cxx-std: c++14
|
|
|
```
|
|
|
|
|
|
#### 命令行覆盖
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++17
|
|
|
```
|
|
|
|
|
|
#### 结果
|
|
|
✅ 使用 **c++17**（命令行优先级更高）
|
|
|
|
|
|
---
|
|
|
|
|
|
### 示例 2：构建模式
|
|
|
|
|
|
#### YAML 配置
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
build-mode: bin
|
|
|
```
|
|
|
|
|
|
#### 命令行覆盖
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --mode=ext
|
|
|
```
|
|
|
|
|
|
#### 结果
|
|
|
✅ 使用 **ext**（命令行优先级更高）
|
|
|
|
|
|
---
|
|
|
|
|
|
### 示例 3：编译选项
|
|
|
|
|
|
#### YAML 配置
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -O2
|
|
|
```
|
|
|
|
|
|
#### 命令行覆盖
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml -O3
|
|
|
```
|
|
|
|
|
|
#### 结果
|
|
|
✅ 优化级别为 **3**（命令行优先级更高）
|
|
|
✅ cxx-flags 仍为 `-Wall -O2`（YAML 配置）
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🔍 不同输入类型的处理
|
|
|
|
|
|
### 类型 1：YAML 配置文件
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++17
|
|
|
```
|
|
|
|
|
|
**执行流程：**
|
|
|
1. ✅ 解析 `project.yml`
|
|
|
2. ✅ 应用 YAML 中的配置
|
|
|
3. ✅ 用 `--cxx-std=c++17` 覆盖
|
|
|
|
|
|
**适用场景：**
|
|
|
- 大型项目
|
|
|
- 需要复杂配置
|
|
|
- 团队协作
|
|
|
|
|
|
---
|
|
|
|
|
|
### 类型 2：单个 PHP 文件
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php hello.php --cxx-std=c++17 -O2
|
|
|
```
|
|
|
|
|
|
**执行流程：**
|
|
|
1. ❌ 跳过 YAML 解析
|
|
|
2. ✅ 直接应用命令行参数
|
|
|
3. ✅ 使用平台默认值作为基础
|
|
|
|
|
|
**适用场景：**
|
|
|
- 快速测试
|
|
|
- 简单脚本
|
|
|
- 临时编译
|
|
|
|
|
|
---
|
|
|
|
|
|
### 类型 3：目录
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php src/ --mode=ext --cxx-std=c++17
|
|
|
```
|
|
|
|
|
|
**执行流程：**
|
|
|
1. ❌ 跳过 YAML 解析
|
|
|
2. ✅ 扫描目录中的所有 PHP 文件
|
|
|
3. ✅ 应用命令行参数
|
|
|
4. ✅ 使用平台默认值作为基础
|
|
|
|
|
|
**适用场景：**
|
|
|
- 批量编译
|
|
|
- 扩展模块
|
|
|
- 多文件项目
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📝 完整示例
|
|
|
|
|
|
### 项目配置
|
|
|
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
version: 1.0.0
|
|
|
|
|
|
cxx-std: c++14
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
|
|
|
ld-flags:
|
|
|
- -lm
|
|
|
|
|
|
sources:
|
|
|
- src/main.php
|
|
|
- src/utils.php
|
|
|
```
|
|
|
|
|
|
### 场景 1：使用默认配置
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml
|
|
|
```
|
|
|
|
|
|
**结果：**
|
|
|
- cxx-std: **c++14**（来自 YAML）
|
|
|
- build-mode: **bin**（来自 YAML）
|
|
|
- cxx-flags: **-Wall -Wextra**（来自 YAML）
|
|
|
|
|
|
---
|
|
|
|
|
|
### 场景 2：部分覆盖
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++17
|
|
|
```
|
|
|
|
|
|
**结果：**
|
|
|
- cxx-std: **c++17**（命令行覆盖）
|
|
|
- build-mode: **bin**（来自 YAML）
|
|
|
- cxx-flags: **-Wall -Wextra**（来自 YAML）
|
|
|
|
|
|
---
|
|
|
|
|
|
### 场景 3：完全覆盖
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++20 --mode=ext -O3
|
|
|
```
|
|
|
|
|
|
**结果：**
|
|
|
- cxx-std: **c++20**（命令行覆盖）
|
|
|
- build-mode: **ext**（命令行覆盖）
|
|
|
- optimize-level: **3**（命令行覆盖）
|
|
|
- cxx-flags: **-Wall -Wextra**（来自 YAML，未被覆盖）
|
|
|
|
|
|
---
|
|
|
|
|
|
### 场景 4：单文件编译
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php test.php --cxx-std=c++17 -O2
|
|
|
```
|
|
|
|
|
|
**结果：**
|
|
|
- cxx-std: **c++17**（命令行）
|
|
|
- build-mode: **bin**（默认值）
|
|
|
- optimize-level: **2**（命令行）
|
|
|
- 无 YAML 配置
|
|
|
|
|
|
---
|
|
|
|
|
|
## ⚙️ 支持的配置项
|
|
|
|
|
|
### 可从 YAML 读取的配置
|
|
|
|
|
|
| 配置项 | YAML 键 | 命令行参数 | 说明 |
|
|
|
|--------|---------|-----------|------|
|
|
|
| 项目名称 | `name` | `--output` | 输出文件名 |
|
|
|
| 构建模式 | `build-mode` / `type` | `--mode` | bin 或 ext |
|
|
|
| C++ 标准 | `cxx-std` | `--cxx-std` | c++14/17/20 |
|
|
|
| 编译选项 | `cxx-flags` | - | C++ 编译标志 |
|
|
|
| 链接选项 | `ld-flags` | - | 链接器标志 |
|
|
|
| 源文件 | `sources` | - | 源文件列表 |
|
|
|
| 忽略列表 | `ignore` | - | 忽略的文件 |
|
|
|
|
|
|
### 只能从命令行设置的配置
|
|
|
|
|
|
| 配置项 | 命令行参数 | 说明 |
|
|
|
|--------|-----------|------|
|
|
|
| 优化级别 | `-O <level>` | 0-3 |
|
|
|
| 调试信息 | `--debug` | 启用调试 |
|
|
|
| 性能分析 | `--profile` | 启用 profiling |
|
|
|
| Sanitizer | `--sanitize` | 内存检测 |
|
|
|
| 并行任务 | `-j <num>` | 并行编译数 |
|
|
|
| 隐藏控制台 | `--no-console` | Windows GUI |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎨 最佳实践
|
|
|
|
|
|
### 1. YAML 中设置默认值
|
|
|
|
|
|
```yaml
|
|
|
# project.yml - 团队共享的默认配置
|
|
|
name: my-app
|
|
|
build-mode: bin
|
|
|
cxx-std: c++17
|
|
|
|
|
|
cxx-flags:
|
|
|
- -Wall
|
|
|
- -Wextra
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 2. 命令行用于临时覆盖
|
|
|
|
|
|
```bash
|
|
|
# 开发时使用调试模式
|
|
|
php bin/compiler.php project.yml --debug
|
|
|
|
|
|
# 发布时使用优化
|
|
|
php bin/compiler.php project.yml -O3
|
|
|
|
|
|
# 测试不同的 C++ 标准
|
|
|
php bin/compiler.php project.yml --cxx-std=c++20
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### 3. 单文件快速测试
|
|
|
|
|
|
```bash
|
|
|
# 不需要 YAML，直接编译
|
|
|
php bin/compiler.php test.php -O2 --cxx-std=c++17
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🐛 常见问题
|
|
|
|
|
|
### Q1: 为什么命令行参数没有生效？
|
|
|
|
|
|
A: 确保使用了正确的参数名称：
|
|
|
|
|
|
```bash
|
|
|
# ✅ 正确
|
|
|
php bin/compiler.php project.yml --cxx-std=c++17
|
|
|
|
|
|
# ❌ 错误（参数名不对）
|
|
|
php bin/compiler.php project.yml --cxx_std=c++17
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q2: YAML 和命令行都设置了同一个值，哪个生效？
|
|
|
|
|
|
A: **命令行参数始终优先**。
|
|
|
|
|
|
```yaml
|
|
|
# project.yml
|
|
|
cxx-std: c++14
|
|
|
```
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml --cxx-std=c++17
|
|
|
# 结果：使用 c++17
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q3: 可以在 YAML 中设置优化级别吗？
|
|
|
|
|
|
A: 目前不支持。优化级别只能通过命令行设置：
|
|
|
|
|
|
```bash
|
|
|
php bin/compiler.php project.yml -O2
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
### Q4: 如何查看当前使用的配置？
|
|
|
|
|
|
A: 编译时会显示相关信息：
|
|
|
|
|
|
```
|
|
|
prepare: project.yml
|
|
|
...
|
|
|
C++ standard: c++17
|
|
|
Build mode: bin
|
|
|
Optimization: O2
|
|
|
...
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 📚 技术实现
|
|
|
|
|
|
### 代码位置
|
|
|
|
|
|
**Translator.php:**
|
|
|
|
|
|
```php
|
|
|
// 1. 构造函数：解析但不应用
|
|
|
public function __construct(string $rootPath)
|
|
|
{
|
|
|
$this->climate->arguments->parse();
|
|
|
// 不立即应用参数
|
|
|
}
|
|
|
|
|
|
// 2. YAML 解析：应用配置
|
|
|
protected function parseProjectYaml(string $path): array
|
|
|
{
|
|
|
// 读取 YAML 并应用到属性
|
|
|
$this->cxxStd = $cfg['cxx-std'] ?? 'c++17';
|
|
|
$this->buildMode = $cfg['build-mode'] ?? 'bin';
|
|
|
// ...
|
|
|
}
|
|
|
|
|
|
// 3. 应用命令行：覆盖配置
|
|
|
protected function applyCommandLineArguments(): void
|
|
|
{
|
|
|
if ($this->climate->arguments->defined('cxx-std')) {
|
|
|
$this->cxxStd = $this->climate->arguments->get('cxx-std');
|
|
|
}
|
|
|
// ...
|
|
|
}
|
|
|
|
|
|
// 4. getFiles：控制流程
|
|
|
public function getFiles(string $path): array
|
|
|
{
|
|
|
if (is_yml($path)) {
|
|
|
$this->parseProjectYaml($path); // 先 YAML
|
|
|
$this->applyCommandLineArguments(); // 后命令行
|
|
|
} else {
|
|
|
$this->applyCommandLineArguments(); // 直接命令行
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 🎉 总结
|
|
|
|
|
|
### 核心原则
|
|
|
|
|
|
1. ✅ **命令行参数优先级最高** - 用户可以随时覆盖
|
|
|
2. ✅ **YAML 提供默认值** - 简化日常使用
|
|
|
3. ✅ **平台默认值兜底** - 确保总能运行
|
|
|
4. ✅ **清晰的执行顺序** - 易于理解和调试
|
|
|
|
|
|
### 优先级图示
|
|
|
|
|
|
```
|
|
|
用户意图
|
|
|
↓
|
|
|
命令行参数 ────────→ 最高优先级，立即生效
|
|
|
↓
|
|
|
YAML 配置 ─────────→ 中等优先级，提供默认值
|
|
|
↓
|
|
|
平台默认值 ────────→ 最低优先级，保证可用性
|
|
|
```
|
|
|
|
|
|
遵循这些规则，您可以灵活地控制编译行为！
|
|
|
|
