跳到主要内容

项目管理(XRobot)

XRobot 是一套面向嵌入式系统(如 STM32)的自动化代码生成工具,配合模块化硬件抽象层 LibXR 使用。它支持模块仓库管理、参数配置和主函数自动生成等工作,极大提高嵌入式项目的工程组织和开发效率。

本章介绍 XRobot 的安装、目录结构、主要功能、命令行工具用法,以及完整的快速上手流程。


安装

推荐通过 pipx 安装(支持隔离环境):

Windows:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install xrobot
# 重启终端

Linux:

sudo apt install pipx
pipx install xrobot
pipx ensurepath
# 重启终端

或者使用 pip 安装:

pip install xrobot

源码安装:

git clone https://github.com/xrobot-org/XRobot.git
cd XRobot
pip install .

目录结构约定

XRobot 推荐如下目录布局进行模块管理和代码生成:

YourProject/
├── Modules/ # 存放模块仓库
│ └── modules.yaml # 仓库列表
│ └── sources.yaml # (可选)模块源索引
├── User/ # 用户配置与生成输出
│ ├── xrobot.yaml # 构造参数配置
│ └── xrobot_main.hpp # 自动生成主函数

功能总览

  • 模块仓库拉取与同步
    自动拉取、同步和递归解析模块仓库,保证依赖与版本一致性。
  • 参数自动提取与配置
    自动解析模块头文件参数,生成和管理 YAML 配置文件。
  • 自动主函数生成
    根据配置自动生成 C++ 入口函数 XRobotMain(),支持多模块、实例和嵌套结构。
  • manifest 解析
    解析并格式化模块头文件清单(manifest)。
  • 模块模板快速生成
    一键生成包含 CI 的标准化模块目录。
  • 多源模块管理
    支持本地/远程 YAML 配置和多模块源索引管理。

命令行工具一览

命令 Command说明Description
xrobot_gen_main自动生成 C++ 主函数Generate main C++ entry source file
xrobot_mod_parser解析模块并打印 manifest 信息Parse and show module manifest
xrobot_create_mod快速创建标准化模块目录Create a new module folder & header
xrobot_init_mod拉取并递归同步所有模块仓库Clone and recursively sync all module repos
xrobot_setup一键初始化工作区和生成主函数One-click workspace setup & main function generate
xrobot_add_mod添加模块仓库或追加模块实例到配置Add repo or append module instance config
xrobot_src_man多源模块仓库管理与索引工具Multi-source module repository management utility

详细参数和用法见后续章节。


快速上手(推荐流程)

# 1. 一键初始化环境、拉取模块、生成主函数(推荐)
# 1. One-click initialize workspace, fetch modules, and generate main function (recommended)
$ xrobot_setup
Starting XRobot auto-configuration...
[INFO] Created default Modules/modules.yaml
Please edit this file; each line should be a full module name like:
- xrobot-org/BlinkLED
- your-namespace/YourModule@dev
[INFO] Created default Modules/sources.yaml
Please configure sources index.yaml for official or custom/private mirrors.
Default official source already included.

$ xrobot_setup
Starting XRobot auto-configuration...
[EXEC] xrobot_init_mod --config Modules/modules.yaml --directory Modules --sources Modules/sources.yaml
[INFO] Cloning new module: xrobot-org/BlinkLED
Cloning into 'Modules/BlinkLED'...
remote: Enumerating objects: 31, done.
remote: Counting objects: 100% (31/31), done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 31 (delta 10), reused 31 (delta 10), pack-reused 0 (from 0)
Receiving objects: 100% (31/31), 4.43 KiB | 2.22 MiB/s, done.
Resolving deltas: 100% (10/10), done.
[SUCCESS] All modules and their dependencies processed.
[INFO] Created default Modules/CMakeLists.txt: Modules/CMakeLists.txt
[EXEC] xrobot_gen_main --output User/xrobot_main.hpp
Discovered modules: BlinkLED
[INFO] Successfully parsed manifest for BlinkLED
[INFO] Writing configuration to User/xrobot.yaml
[SUCCESS] Generated entry file: User/xrobot_main.hpp

All done! Main function generated at: User/xrobot_main.hpp

# 2. 单独拉取/同步模块仓库(可选)
# 2. Pull or sync module repositories separately (optional)
$ xrobot_init_mod --config Modules/modules.yaml --directory Modules
[INFO] Updating module: xrobot-org/BlinkLED
Already up to date.
Already on 'master'
Your branch is up to date with 'origin/master'.
[SUCCESS] All modules and their dependencies processed.

# 3. 创建模块
# 3. Create a module
$ xrobot_create_mod MySensor --desc "IMU interface module" --hw i2c1
[OK] Module MySensor generated at Modules/MySensor

# 4. 查看模块信息
# 4. View module information
$ xrobot_mod_parser --path ./Modules/MySensor/

=== Module: MySensor.hpp ===
Description : IMU interface module

Constructor Args :
Required Hardware : i2c1
Depends : None

# 5. 添加模块仓库(如需自定义来源)
# 5. Add a module repository (custom source, optional)
$ xrobot_add_mod your-namespace/YourModule@main
[SUCCESS] Added repo module 'your-namespace/YourModule@main' to Modules/modules.yaml

# 6. 添加模块实例
# 6. Add a module instance
$ xrobot_add_mod MySensor
[SUCCESS] Appended module instance 'MySensor' as id 'MySensor_0' to User/xrobot.yaml

# 7. 查看模块实例
# 7. View module instances
$ cat ./User/xrobot.yaml
global_settings:
monitor_sleep_ms: 1000
modules:
- name: BlinkLED
constructor_args:
blink_cycle: 250
- id: MySensor_0
name: MySensor
constructor_args: {}

# 8. 重新生成主函数(支持自动扫描和配置)
# 8. Regenerate main function (auto scan & config supported)
$ xrobot_gen_main --output User/xrobot_main.hpp
Discovered modules: BlinkLED, MySensor
[SUCCESS] Generated entry file: User/xrobot_main.hpp

# 9. 查看主函数
# 9. View main function
$ cat ./User/xrobot_main.hpp
#include "app_framework.hpp"
#include "libxr.hpp"

// Module headers
#include "BlinkLED.hpp"
#include "MySensor.hpp"

static void XRobotMain(LibXR::HardwareContainer &hw) {
using namespace LibXR;
ApplicationManager appmgr;

// Auto-generated module instantiations
static BlinkLED blinkled(hw, appmgr, 250);
static MySensor MySensor_0(hw, appmgr);

while (true) {
appmgr.MonitorAll();
Thread::Sleep(1000);
}
}