项目管理(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);
}
}