bingo ​

版本信息 ​

1. 组件概述 ​

1.1 组件简介 ​

bingo 是 openUBMC BMC 开发的工程工具和最佳实践的承载者，提供一站式命令行工具，降低组件开发成本。bingo 作为 openUBMC 工程体系的核心枢纽，统一管理组件创建、代码自动生成、构建出包、开发者测试、依赖分析、版本发布等 BMC 开发全流程，是 openUBMC 开发者日常使用的核心工具。

1.2 解决什么问题 ​

bingo 解决 BMC 软件开发中的工程效率问题：将分散的构建脚本、代码生成工具、依赖管理、测试框架整合为统一 CLI，开发者无需手动维护 Conan 配置、交叉编译 profile、MDS 模型到代码的映射等繁琐工程细节，通过一条 bingo 命令即可完成从建模到出包的端到端流程。

1.3 核心功能 ​

• 核心功能一：组件全生命周期管理——通过 bingo new 创建组件脚手架、bingo gen 代码自动生成（Lua/C）、bingo build 构建、bingo test 测试、bingo deploy 部署，覆盖组件从创建到发布的完整流程
• 核心功能二：产品集成构建——在 manifest 仓库中执行 bingo build，基于 Conan 依赖体系自动拉取组件、交叉编译、组装 rootfs 并生成 HPM 固件包，支持多单板、多构建类型和发布阶段
• 核心功能三：工程辅助能力——包括依赖与接口分析（bingo analysis）、版本差异追踪（bingo diff）、源码拉取（bingo fetch）、参数配置（bingo config）、版本升级（bingo upgrade）、BMC Studio 管控（bingo studio）和 Skill 管理（bingo skill）

1.4 关键术语表 ​

1.5 外部交互边界图 ​

bingo 与以下外部系统交互：

• Conan 远程仓库：拉取/上传组件包，解析依赖关系
• Git 仓库：通过 gitpython 拉取源码、获取版本信息和分支差异
• BMC Studio：启动/停止建模服务，执行 CSR 语法检查
• PyPI：bingo 自身的安装和升级源（openubmc-bingo 包）
• Skills Marketplace（GitCode）：同步 AI agent 技能到本地
• HPM 签名服务：支持 SignServer 签名、服务器签名和自签名三种模式
• 板子部署：通过 SFTP/HTTPS 将产品包部署到目标 BMC 设备

2. API 使用说明与示例 ​

2.1 bingo build ​

功能说明 ​

构建组件包或产品 HPM 包。bingo 具有配置探测能力：在组件目录执行时构建组件包，在 manifest 目录执行时构建产品集成包。

参数说明 ​

组件构建参数：

产品构建参数：

返回值与异常 ​

应用场景 ​

• 在组件源码目录构建组件 Conan 包并上传到远端仓库
• 在 manifest 仓库构建产品 HPM 包或发布包
• 开发调试阶段使用 -bt debug --stage dev 快速构建
• 正式发布阶段使用 -bt release --stage stable 构建正式包

限制条件 ​

• 必须在合法组件目录（包含 mds/service.json）或 manifest 目录（包含 .bmcgo/config）下执行
• 组件构建和产品构建互斥，bingo 根据目录类型自动切换
• 多个 bingo build 进程在同一 manifest 下并发执行会被互斥锁阻止
• Conan 版本需要与组件/产品配置匹配（1.0 或 2.0），bingo 会自动检测并切换

调试示例 ​

命令行调试 ​

组件构建：

bingo build -bt debug --stage rc

产品 HPM 包构建：

bingo build -t personal -b openUBMC -bt release --stage rc

产品发布包构建：

bingo build -t publish -b openUBMC -bt release --stage stable --signature_type sm2

2.2 bingo gen ​

功能说明 ​

代码自动生成，支持 Lua 和 C 语言。根据 MDS 模型定义自动生成服务端/客户端代码框架，大幅减少手工编码量。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 新组件创建后首次生成代码框架
• MDS 模型变更后重新生成代码以同步接口定义
• 支持 C、C++ 和 Lua 语言代码生成，C/C++ 组件需在 service.json 中配置 "language" 字段

限制条件 ​

• 必须在组件目录下执行
• C/C++ 组件需要在 service.json 中配置 "language" 字段
• 生成代码会覆盖 gen 目录下的已有文件，手工修改的代码应放在非 gen 目录

调试示例 ​

命令行调试 ​

bingo gen
# 指定 service 文件路径生成代码
bingo gen -s mds/service.json
# 生成时包含模板文件
bingo gen -w

2.3 bingo test ​

功能说明 ​

执行组件开发者测试（DT），支持单元测试、集成测试、模糊测试、Mock 测试和 ASAN 内存检测。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 组件开发过程中执行单元测试验证功能正确性
• 代码提交前执行集成测试验证接口行为
• 使用模糊测试发现潜在安全漏洞
• 使用 Mock 测试隔离依赖组件进行局部验证
• 使用 ASAN（-as）检测内存错误

限制条件 ​

• 必须在合法组件目录下执行（包含 mds/service.json）
• 测试默认会先构建组件，如需跳过构建可使用 -wb 参数
• 使用 ASAN 测试需添加 -as 参数
• 模糊测试用例可通过 -fg 生成，通过 -ft 执行

调试示例 ​

命令行调试 ​

# 单元测试
bingo test -ut
# 集成测试
bingo test -it
# 不重新构建直接测试
bingo test -ut -wb
# ASAN 内存检测
bingo test -ut -as
# Mock 测试
bingo test -mt
# 生成模糊测试用例并执行
bingo test -fg && bingo test -ft

2.4 bingo new ​

功能说明 ​

创建新的 openUBMC 组件，自动生成组件脚手架代码和目录结构。

参数说明 ​

返回值与异常 ​

应用场景 ​

• 开发新的 openUBMC 业务组件
• 快速搭建包含 MDS 模型、构建脚本、测试框架的标准组件框架

限制条件 ​

• 当前目录下不能已存在同名子目录
• 目前仅支持 Lua 语言和 application 类型

调试示例 ​

命令行调试 ​

bingo new -n my_component -t application -l lua -conan 1.0
# 使用 Conan 2.0 模板
bingo new -n my_component -t application -l lua -conan 2.0

2.5 bingo deploy ​

功能说明 ​

将组件及其依赖部署至 temp/rootfs 目录，先构建再部署。

参数说明 ​

与 bingo build 组件构建参数一致。

返回值与异常 ​

应用场景 ​

• 本地调试时将组件部署到 temp/rootfs 目录模拟运行环境
• 验证组件在目标文件系统中的安装布局

调试示例 ​

命令行调试 ​

bingo deploy -bt debug --stage dev

2.6 bingo analysis ​

功能说明 ​

依赖和接口分析，支持组件和 manifest 两个级别，用于理解组件间依赖关系和接口调用链。

参数说明 ​

调试示例 ​

命令行调试 ​

bingo analysis -b openUBMC

2.7 bingo fetch ​

功能说明 ​

基于参数指定的单个、部分或全量组件版本拉取源代码。

参数说明 ​

调试示例 ​

命令行调试 ​

# 拉取单个组件
bingo fetch -pi iam/1.20.31@openUBMC.release/rc
# 拉取全量组件
bingo fetch --all
# 指定单板拉取配套源码
bingo fetch -b openUBMC
# 根据平台拉取源码
bingo fetch -sys bmc_core

2.8 bingo diff ​

功能说明 ​

获取两个产品版本间组件版本变更时的合并记录。

参数说明 ​

调试示例 ​

命令行调试 ​

bingo diff abc123 def456

2.9 bingo config ​

功能说明 ​

bingo 参数配置，支持代理、签名、部署、插件等运行参数的持久化管理。

参数说明 ​

通过 bingo config <section>.<key>=<value> 格式设置配置项。可用配置项包括：

调试示例 ​

命令行调试 ​

# 关闭技能自动同步
bingo config skill.sync=false
# 设置代理
bingo config env.http_proxy=http://proxy:8080
# 查看生效配置
bingo config -l
# 取消全局配置
bingo config --unset env.http_proxy
# 设置本地配置
bingo config --local env.http_proxy=http://proxy:8080
# 设置部署配置
bingo config deploy-192.168.1.1.port=443

2.10 bingo upgrade ​

功能说明 ​

升级 bingo 自身版本，支持升级到最新版本、指定版本和版本范围。

参数说明 ​

调试示例 ​

命令行调试 ​

# 升级到最新版本
bingo upgrade
# 升级到指定版本
bingo upgrade --version bingo=0.7.50
# 列出可安装版本
bingo upgrade -l

2.11 bingo studio ​

功能说明 ​

执行 BMC Studio 启动/停止操作，用于建模服务的管控。

调试示例 ​

命令行调试 ​

bingo studio start
bingo studio stop

2.12 bingo check ​

功能说明 ​

CSR 语法正确性与模型一致性检查，用于验证组件服务资源的合规性。

参数说明 ​

调试示例 ​

命令行调试 ​

bingo check
# 指定输出格式为 json
bingo check --csr-format json
# 全量检查
bingo check --no-csr-incremental

2.13 bingo skill ​

功能说明 ​

技能管理，用于从 GitCode Skills Marketplace 同步和管理 AI agent 技能到本地环境。

调试示例 ​

命令行调试 ​

bingo skill sync

3. 组件扩展案例 ​

3.1 扩展能力概述 ​

bingo 提供功能模块动态加载机制，开发者可通过在 bmcgo/functional/ 目录下编写 Python 模块来扩展 bingo 命令。每个功能模块需实现 if_available（可用性检查）、command_info（命令元信息）和 BmcgoCommand（命令执行类）三个接口，bingo CLI 在启动时自动扫描并注册符合条件的命令。

3.2 扩展点说明 ​

扩展点位于 bmcgo/functional/ 目录，bingo 在初始化时通过 _load_functional 方法扫描该目录下所有 .py 文件（以 _ 开头的除外），动态导入并注册到对应命令组（Misc/Component/Integrated/Studio/Conan Index/SDK）中。

3.3 二次开发指导 ​

步骤一：创建功能模块文件 ​

在 bmcgo/functional/ 目录下创建新的 .py 文件，如 my_command.py。

步骤二：实现三个必须接口 ​

• if_available(bconfig: BmcgoConfig)：返回布尔值，控制命令是否在当前环境下显示
• command_info: CommandInfo：定义命令组、名称、描述、是否隐藏和帮助信息
• class BmcgoCommand：实现命令执行逻辑，构造函数接收 bconfig 和 args，run() 方法执行具体操作

示例代码 ​

from bmcgo import misc
from bmcgo.bmcgo_config import BmcgoConfig
from bmcgo.utils.tools import Tools

tools = Tools("my_command")
log = tools.log

command_info: misc.CommandInfo = misc.CommandInfo(
    group=misc.GRP_MISC,
    name="mycmd",
    description=["我的自定义命令"],
    hidden=False
)

def if_available(bconfig: BmcgoConfig):
    return True

class BmcgoCommand:
    def __init__(self, bconfig: BmcgoConfig, *args):
        self.bconfig = bconfig
        log.info("自定义命令执行")

    def run(self):
        log.success("自定义命令完成")
        return 0

验证方法 ​

1. 在 bingo 源码目录执行 sh install_local.sh 安装到本地
2. 在任意 bingo 项目目录执行 bingo help，检查是否出现新命令
3. 执行 bingo mycmd 验证命令逻辑是否正确

注意事项 ​

• 功能模块文件不能以 _ 开头
• 必须实现 if_available、command_info 和 BmcgoCommand 三个接口，否则 bingo 会跳过该模块
• command_info.group 必须属于已有命令组（Misc commands、Component commands、Integrated commands、Studio commands、Conan Index commands、SDK commands）
• 新增功能模块后需重新安装 bingo（sh install_local.sh）才能生效

4. 日志说明 ​

4.1 一键日志收集 ​

4.2 关键日志信息 ​

4.3 日志级别控制 ​

通过环境变量 LOG 控制日志详细程度：

使用方式：

export LOG=debug && bingo build

5. 问题定界指南 ​

5.1 典型问题定界 ​

5.2 错误码速查表 ​

5.3 调试方法 ​

开启调试日志 ​

export LOG=debug
bingo build -bt debug --stage dev

复现问题方法 ​

1. 前置条件设置：确保 bingo 已正确安装（pip3 install openubmc-bingo），在目标目录下有 .bmcgo/config 或 mds/service.json
2. 操作步骤：设置 export LOG=debug，执行目标 bingo 命令
3. 预期现象：命令成功完成或输出详细错误信息定位到具体代码行

VSCode 调试 ​

bingo 提供了 VSCode 调试脚本 debug.py，修改其中的配置后可直接在 VSCode 中断点调试：

# debug.py
DEBUG_TARGET_RELATIVE_PATH = "."      # 调试目标目录
DEBUG_COMMAND = "bingo help"           # 需调试的命令

6. 常见问题解答 ​

Q1：bingo help 未显示预期命令 ​

• 问题描述：在某个目录执行 bingo help，预期出现的命令未显示
• 一句话答案：bingo 根据目录下的配置文件动态显示可用命令
• 根因说明：bingo 通过检测 .bmcgo/config 或 mds/service.json 判断项目类型，只显示对应类型的命令组
• 解决方案：确认当前目录包含正确的配置文件，manifest 仓需要 .bmcgo/config 中配置 manifest.folder，组件仓需要 mds/service.json
• 适用版本：所有版本

Q2：Conan 版本不匹配导致构建失败 ​

• 问题描述：bingo build 报错 Conan 版本不匹配
• 一句话答案：bingo 会自动检测并切换 Conan 版本
• 根因说明：组件 conanfile.py 的 required_conan_version 或 manifest 的 conan.version 配置与当前安装的 Conan 版本不一致
• 解决方案：bingo 会自动安装正确版本并提示重新执行，按提示操作即可
• 适用版本：所有版本

Q3：bingo build 构建速度慢 ​

• 问题描述：bingo build 执行时间过长
• 一句话答案：利用 Conan 缓存和增量构建加速
• 根因说明：全量构建每次都重新编译所有依赖，Conan 缓存未启用
• 解决方案：避免使用 -nc（no_cache）参数，确保 ~/.conan/data 缓存目录正常；产品构建使用 -ucc 更新缓存而非全量重建
• 适用版本：所有版本

Q4：bingo gen 后手工代码被覆盖 ​

• 问题描述：执行 bingo gen 后之前手写的代码被覆盖
• 一句话答案：手工代码不应放在 gen 目录下
• 根因说明：bingo gen 输出到 gen 目录，每次执行会覆盖该目录内容
• 解决方案：将手工编写的业务逻辑代码放在 gen 目录之外（如 src/lualib/lib），仅通过 gen 生成框架代码
• 适用版本：所有版本

Q5：bingo 升级失败 ​

• 问题描述：执行 bingo upgrade 报错
• 一句话答案：检查 pip3 网络和权限
• 根因说明：pip3 安装失败通常由网络不通、PyPI 源不可达或权限不足导致
• 解决方案：配置正确的 pip 源和代理（bingo config env.http_proxy），或使用 APT 源安装（apt install openubmc-bingo）
• 适用版本：所有版本

附录 ​

附录A 参考资料 ​

• openUBMC 官网
• openubmc-bingo PyPI
• Conan 官方文档
• openUBMC 组件构建与发布指南

附录B 修订记录 ​