# Bianbu 配置包

这个项目提供了 Bianbu 发行版的配置管理系统，支持多变体、多板卡的差异化配置。

## 项目简介

Bianbu 配置包是一个模块化的系统配置管理工具，主要特点：

- **变体分离**：支持 star、lxqt、desktop 等多个变体，每个变体有独立的配置包
- **板卡适配**：针对不同硬件板卡（如 k1-x-muse-pi-pro 等）提供差异化配置
- **钩子机制**：通过可执行钩子脚本在系统启动的不同阶段执行配置任务
- **文件覆盖**：支持通过 overlay 机制覆盖系统默认文件
- **防重复执行**：内置执行标记机制，确保配置脚本不会重复执行

## 目录结构

```text
bianbu-config/
├── hooks/                     # 配置钩子脚本目录
│   ├── 50-template-config     # 钩子脚本模板
│   ├── lxqt/basic/            # lxqt 变体的基础阶段钩子
│   └── desktop/basic/         # desktop 变体的基础阶段钩子
├── target_overlay/            # 系统文件覆盖目录
│   ├── lxqt/                  # lxqt 变体的覆盖文件
│   └── desktop/               # desktop 变体的覆盖文件
├── common                     # 通用脚本库（系统信息检测等）
└── debian/                    # Debian 包构建配置
    ├── control                # 包依赖和描述
    ├── *-config.install       # 各变体包的安装配置
    └── *-config.postinst      # 各变体包的安装后脚本
```

### 核心组件说明

- **hooks/** - 按变体和阶段组织的配置钩子脚本
  - `basic/` - 基础服务阶段（在 local-fs.target 之后，basic.target 之前执行）
- **common** - 通用脚本库，包含系统信息检测函数和日志工具
- **target_overlay/** - 按变体组织的系统文件覆盖目录

## 添加新变体

1. 在 `hooks/` 下创建变体目录
2. 在 `target_overlay/` 下创建变体目录
3. 修改 `debian/control` 添加变体包
4. 运行 `./debian/generate-install.sh bianbu-<variant>-config <variant>`

## 添加新钩子

### 步骤

1. **复制模板**：将 `hooks/50-template-config` 复制到目标位置

   ```bash
   cp hooks/50-template-config hooks/<variant>/<stage>/<number>-<name>-config
   ```

2. **命名规范**：
   - `<variant>`: 变体名称，如 `lxqt`、`desktop`
   - `<stage>`: 阶段名称
     - `basic`: 基础服务阶段（在 local-fs.target 之后，basic.target 之前执行）
   - `<number>`: 执行顺序，数字越小越早执行（如 `50`、`60`）
   - `<name>`: 功能描述性名称（如 `wlroots`、`labwc`）

3. **编辑内容**：根据具体需求修改钩子脚本内容

4. **设置权限**：确保钩子文件有可执行权限

   ```bash
   chmod +x hooks/<variant>/<stage>/<number>-<name>-config
   ```

### 示例

```bash
# 为 lxqt 变体添加一个 wayland 配置钩子
cp hooks/50-template-config hooks/lxqt/basic/55-wayland-config
chmod +x hooks/lxqt/basic/55-wayland-config
```

## 开发指南

### 钩子脚本开发

钩子脚本应该遵循以下规范：

1. **防重复执行**：使用 `is_script_executed` 检查，避免重复执行
2. **标记完成**：完成后调用 `mark_script_executed` 标记脚本已执行
3. **板卡判断**：由于脚本已按变体分目录，只需判断板卡类型（`board`）
4. **错误处理**：适当处理错误情况，返回合适的退出码
5. **日志记录**：使用 `log_info`、`log_warn`、`log_error` 记录日志

### 脚本模板结构

```bash
#!/bin/bash
# 脚本功能描述

. /usr/share/bianbu-config/common

if is_script_executed; then
    exit 0
fi

IFS=' ' read -r _ board <<<"$(detect)"

configure_something() {
    log_info "配置 something 功能"
    # 配置逻辑...
    return 0
}

case "${board}" in
    k1-x-muse-pi-pro)
        configure_something
        ;;
    *)
        log_info "当前板卡 ${board} 不需要此配置"
        ;;
esac

mark_script_executed
```

### 文件覆盖规则

覆盖系统文件时应该：

1. **目录结构**：在 `target_overlay/<variant>/` 下按照目标路径创建文件
2. **路径映射**：如果目标路径为 `/etc/abc/def`，则在 `target_overlay/<variant>/etc/abc/` 下创建 `def` 文件
3. **权限设置**：注意设置正确的目录和文件权限

## 变体分离说明

钩子脚本已按变体分离到不同目录：

- `hooks/lxqt/basic/` - lxqt 变体的基础阶段钩子
- `hooks/desktop/basic/` - desktop 变体的基础阶段钩子

因此钩子脚本内部只需要判断板卡类型 (`board`)，无需再判断变体类型 (`variant`)。
