提案预览 neo-generate plugin，有简单层级依赖处理的 oebuild generate · Pull Request !169 · openEuler/oebuild

# Neo oebuild 规范讨论

## 0. samples

### Cli mode

期望效果
![输入图片说明](https://foruda.gitee.com/images/1764062522634335199/b3614971_1979072.png "屏幕截图")
## 1\. 核心思路

本系统的核心目标是

* **系统化**：不再是零散的脚本修补，在oebuild neo-generate 生成到 Bitbake 的全局变量（`local.conf`, `bblayers.conf`）追加内容的过程中，会做一些简单的依赖管理工作
  * **简单化**：
    > 聚焦于“正向依赖”和“简单冲突”。我们**不处理**复杂的负向依赖逻辑和冲突，这应下沉到 Bitbake 配方中处理。
    > 简单来源：文件系统目录结构即分类标准，YAML 文件即特性定义
  * **向前兼容**: 尽可能保证oebuild neo-generate cli 的使用习惯和 oebuild generate 无差

-----

## 2\. 核心规则详解 (Core Rules)

### 2.1 目录与 ID 命名规则

特性定义暂时存储于 `yocto-meta-openeuler/.oebuild/nightly-features/` 目录下，遵循以下严格的 ID 解析规则：

1.  **物理结构**：`nightly-features/<category_id>/<leaf_id>.yaml`, 不会有更多级
2.  **Full ID**：`<category_id>/<leaf_id>`（全局唯一标识）。
3.  **语法糖**：
      * 当文件名与目录名相同时（即 `category_id == leaf_id` 且 feat is not sub feat），全 ID `<category_id>/<category_id>` 可简写为 **`<category_id>`**。
      * *示例*：`mcs/mcs.yaml` 的 ID 为 `mcs`，其下定义的子特性可直接引用为 `mcs/micrun`。

### 2.2 YAML Schema 规范

每个 YAML 文件描述一个特性节点。

| 字段 | 必填 | 说明 |
| :--- | :--- | :--- |
| **`id`** | 是 | 叶子标识符（Leaf ID），不可为 "self"。 |
| **`name`** | 否 | 显示名称，默认为 ID。 |
| **`machines`** | 否 | 支持的机器列表。空列表 `[]` 或省略表示支持**所有机器**。 |
| **`config`** | 否 | 定义注入内容：<br>- `local_conf`: 追加到 local.conf 的行列表。<br>- `layers`: 追加到 bblayers.conf 的层路径。 |
| **`sub_feats`** | 否 | **内联**定义的子特性列表。**注意**：禁止多层递归定义（即 sub\_feats 中不能再套 sub\_feats）。 |
| **`one_of`** | 否 | **强制单选组**。列出的 ID 中必须且只能选中一个。 |
| **`choice`** | 否 | **可选多选组**。列出的 ID 中可以选择 0-N 个。 |
| **`dependencies`** | 否 | **前置依赖**。若任一依赖项不可用，当前特性将被隐藏。 |
| **`selects`** | 否 | **自动选中**。启用当前特性时，强制启用列表中的特性。 |

### 2.3 `self` 关键字解析

为了简化 YAML 编写，引入 `self` 关键字进行相对引用。

* **解析逻辑**：`self` 在解析时会被替换为当前特性的完整命名空间。
  * **场景**：mica/mica.yaml 在 `sub_feats` 定义了 `xen`，在 `one_of` 中引用时写作 `self/xen`，解析器会将其展开为 `mica/xen`。

### 2.4 可见性与依赖传播 (Strict Mode)

特性在 Menuconfig 或 CLI 中**有效/可见**的充要条件：

1.  **machine匹配**：当前 `-p <machine>` 在特性的 `machines` 列表中。
2.  **依赖满足**：所有 `dependencies` 均已启用且支持当前机器。
3.  **父级启用**：若为子特性，其父特性必须处于启用状态。

-----

## 3\. 使用方法与交互 (Usage & CLI)

### 3.1 命令行接口

基本语法：

```bash
oebuild neo-generate -p <machine> [-f <feature_identifier>]...
```

### 3.2  ID 解析策略

为了提升用户体验，CLI 参数支持模糊匹配，解析优先级如下（由高到低）：

1.  **精确全 ID (Full ID)**：
      * `mcs/mica` -\> 命中唯一特性。
2.  **唯一叶子 ID (Unique Leaf)**：
      * `k3s` -\> 若全局只有 `containers/k3s`，则命中。
      * *异常*：若存在 `net/k3s` 和 `containers/k3s`，报 **Ambiguity Error**。
3.  **类别根特性 (Category Root)**：
      * `mcs` -\> 视为 `mcs/mcs`（当该文件存在时）。
      * *说明*：这允许用户用目录名直接激活该目录下的同名主配置文件。
4.  **子特性短匹配 (Sub-feature Short Match)**：
      * `xen` -\> 尝试匹配 `*/xen` 或 `*/*/xen`。
      * *优先级*：若顶层特性与子特性重名，顶层特性优先。

### 3.3 状态管理与列表展示

系统维护一个 `<build_dir>/compile.yaml` 作为状态快照。

**列表展示 (`--list`)**：
不再使用扁平列表，而是采用树状缩进结构，直观展示层级关系。

```text
$ oebuild neo-generate --list
...
│ mica                              [支持机器列表...]
│   - mica/baremetal                  (Default)
│   - mica/xen                        
│   - mica/jailhouse                  
│   - mica/micrun                            
...
```

-----

## 4\. 典型配置示例 (Typical Examples)

### 场景一：基础特性 (Simple Feature)

最简单的特性，仅追加配置。

```yaml
# nightly-features/toolchain/clang.yaml
id: clang
name: Clang Toolchain
machines: [qemu-aarch64, raspberrypi4-64] # 限制支持的架构
config:
  layers:
    - yocto-meta-openeuler/meta-clang
  local_conf:
    - 'DISTRO_FEATURES:append = " clang"'
    - 'DISTRO_FEATURES_NATIVE:append = " clang "'
```

### 场景二：互斥选择与子特性 (Mutually Exclusive)

使用 `sub_feats` 定义选项，使用 `one_of` 实施互斥约束。

```yaml
# nightly-features/mcs/mica.yaml
id: mica
name: MCS Virtualization
# 1. 定义子选项
sub_feats:
  - id: baremetal
    name: Baremetal (AMP)
    config:
      local_conf: ['MCS_FEATURES ?= "openamp"']
  - id: xen
    name: Xen Hypervisor
    config:
      local_conf: ['MCS_FEATURES ?= "xen"']

# 2. 实施互斥逻辑
one_of:
  - self/baremetal
  - self/xen

# 3. 默认值
default_one_of: self/baremetal
```

*用户行为*：

* `oebuild generate -f mica` -\> 自动选中 `mica` 和 `mica/baremetal`。
  * `oebuild generate -f mica -f xen` -\> 自动选中 `mica` 和 `mica/xen`。
  * `oebuild generate -f mica -f baremetal -f xen` -\> **报错：互斥冲突**。

### 场景三：依赖链 (Dependency Chain)

K3s 依赖容器化的ko， containers特性提供了 一系列ko以及可选的外部容器引擎

```yaml
# nightly-features/containers/k3s.yaml
id: k3s
dependencies: 
  - containers  # 必须先启用 containers 特性
selects:
  - self/agent  # 启用 k3s 时，默认带上 agent

sub_feats:
  - id: agent
    name: K3s Agent
  - id: server
    name: K3s Server
```

-----

## 5\. 实现状态与后续计划 (Roadmap)

### 5.1 当前实现 (Current Status)

* **插件位置**：`oebuild/app/plugins/neo-generate`
  * **范围**：
      * [x] 完整的 YAML 解析与校验。
      * [x] 基于递归逻辑的依赖计算（Step A/B/C）。
      * [x] `compile.yaml` 状态文件的生成（与oebuild generate产物保持无序一致，条目相同，顺序可能不同）。
      * [x] 树状 `--list` 展示。
      * [ ] menuconfig 基本 layout
      * [ ] menuconfig legacy样式靠拢
      * [ ] menuconfig 依赖可见性，以及反选
  * **corner case**测试：
      * [ ] 验证
      * 大模型生成了测试集，已过但是没有review测试集内容。

### 5.2 限制与占位符 (Limitations)

* ~~**Conflicts (冲突)**：关键字 `conflicts` 目前仅作为 Schema 中的占位符。解析器包含一个简单的逻辑分支，但尚未执行复杂的反向依赖计算。建议目前的冲突主要通过 `one_of`（互斥组）或文档规范解决。~~ 不再需要 conflict
  * **Yocto 变量调整**：MCS_FEATURES等某些分类不清的全局变量控制可能需要调整，或许可以在yocto中改变定义，或者也可以在oebuild neo-generate中完成分派

### 5.3 后续计划 (Future Plans)

1.  **Menuconfig neo-generate实现**：交互、分级选择更加容易方便，靠近 kernel menuconfig 的选择风格，但是不需要复杂的SAT bool计算。
1.  **多层级子特性支持**：评估是否需要放开 `sub_feats` 的非递归限制（目前为了保持简单性而禁止）。

openEuler/oebuild .gitee-modal { width: 500px !important; }

搜索帮助

openEuler/oebuild