Example Component - RT-Thread Rust 组件示例

概述

example_component 是一个基于 RT-Thread 的 Rust 组件示例，展示了如何在 RT-Thread 系统中实现、注册和管理 Rust 组件。该项目采用统一的组件注册架构，避免了组件重复注册问题，并支持基于 RT-Thread 配置的条件编译。

项目结构

example_component/
├── SConscript                      # SCons 构建脚本
├── component_registry/             # 统一组件注册程序
│   ├── Cargo.toml                  # 注册程序配置
│   └── src/
│       └── lib.rs                  # 注册程序实现
├── log/                            # 日志组件示例
│   ├── Cargo.toml                  # 日志组件配置
│   └── src/
│       ├── lib.rs                  # 日志组件实现
│       └── logging.rs              # 日志功能模块
└── tools/                          # 构建工具
    ├── build_component.py          # 组件构建工具
    └── feature_config_component.py # 特性配置

核心特性

1. 统一组件注册架构

避免重复注册: 通过 component_registry 统一管理所有组件的注册，避免多个组件重复注册导致的冲突
条件编译支持: 根据 RT-Thread 配置选择性编译和注册组件
模块化设计: 每个组件独立实现，通过注册程序统一管理

2. 特性配置系统

基于 RT-Thread 配置: 特性启用完全基于 RT-Thread 的配置项，无需额外配置
自动特性映射: 构建系统自动将 RT-Thread 配置映射为 Rust 特性
依赖检查: 自动检查组件依赖关系，确保构建一致性

3. 构建系统集成

SCons 集成: 与 RT-Thread 的 SCons 构建系统完全集成
增量构建: 支持清理和增量构建
交叉编译: 支持 RISC-V 等目标架构的交叉编译

组件详解

Component Registry (组件注册程序)

component_registry 是整个架构的核心，负责统一管理所有组件的注册。

主要功能

统一入口点: 提供 rust_component_registry 作为所有组件的统一注册入口
条件编译: 只在相应特性启用时才包含和注册对应组件
避免冲突: 确保每个组件只被注册一次

Log Component (日志组件)

log 组件提供了 Rust 风格的日志功能，包括多个日志级别和命令行接口。

主要功能

多级别日志: 支持 INFO、WARN、ERROR、DEBUG、TRACE 等日志级别
命令行接口: 提供 log_info、log_warn、log_error 等命令
条件编译: 只在 enable-log 特性启用时编译

使用示例

// 在代码中使用日志宏
info!("这是一条信息日志");
warn!("这是一条警告日志");
error!("这是一条错误日志");

命令行使用

# 在 RT-Thread 命令行中使用
msh> log_info    # 打印信息日志
msh> log_warn    # 打印警告日志
msh> log_error   # 打印错误日志

特性配置

配置映射

在 tools/feature_config_component.py 中定义了 RT-Thread 配置到 Rust 特性的映射：

CONFIG_COMPONENT_FEATURE_MAP = {
    'RUST_LOG_COMPONENT': {
        'feature': 'enable-log',
        'dependency': 'em_component_log',
        'description': 'Enable Rust log component integration'
    }
}

启用组件

要启用日志组件，需要在 RT-Thread 配置中设置：

// 通过 menuconfig 设置
Enable Rust component support -> Auto-initialize Rust log component

开发指南

添加新组件

创建组件目录

cargo new --lib example_component/new_component
cd example_component/new_component

创建 Cargo.toml

[package]
name = "em_component_new"
version = "0.1.0"
edition = "2021"

[lib]
name = "em_component_new"
crate-type = ["staticlib"]

[dependencies]
rt-rust = { path = "../../rust" }
macro_main = { path = "../../rust/macro-main" }

[features]
default = []
enable-new = []

实现组件功能

// src/new.rs
// 新组件的实现代码

// src/lib.rs
#![no_std]
// 导出需要的库

更新特性配置

# 在 tools/feature_config_component.py 中添加
CONFIG_COMPONENT_FEATURE_MAP = {
   # ... 现有配置 ...
   'RUST_NEW_COMPONENT': {
       'feature': 'enable-new',
       'dependency': 'em_component_new',
       'description': 'Enable new component integration'
   }
}

更新注册程序

# 在 component_registry/Cargo.toml 中添加
[dependencies]
em_component_new = { path = "../new_component", optional = true }

[features]
enable-new = ["em_component_new", "em_component_new/enable-new"]

// 在 component_registry/src/lib.rs 中注册
#[cfg(feature = "enable-new")]
use em_component_new;

fn component_registry_main() {
   #[cfg(feature = "enable-new")]
   {
       println!("Component registry: New component enabled");
   }
   // ... 其他组件 ...
}

组件开发最佳实践

使用条件编译: 所有功能都应该用 #[cfg(feature = "...")] 包装
避免直接注册: 不要在组件中直接使用组件注册宏，让 component_registry 统一管理
提供命令接口: 为组件功能提供命令行接口，方便测试和使用
文档完整: 为每个组件提供详细的文档和使用示例

故障排除

常见问题

编译失败
- 检查 Rust 工具链是否正确安装
- 确认目标架构 (如 riscv64imac-unknown-none-elf) 已安装
- 检查依赖路径是否正确
特性未启用
- 确认 RT-Thread 配置中已设置相应的宏定义
- 检查 feature_config_component.py 中的映射配置
- 查看构建日志中的特性启用信息
链接错误
- 确认所有依赖组件都已正确构建
- 检查 Cargo.toml 中的依赖配置
- 验证库文件路径和名称

依赖关系

RT-Thread Config
      ↓
Feature Mapping
      ↓
Rust Features
      ↓
Component Registry ← Individual Components
      ↓
RT-Thread System

component_cn.md 6.2 KB 履歴 Raw

Example Component - RT-Thread Rust 组件示例

概述

项目结构

核心特性

1. 统一组件注册架构

2. 特性配置系统

3. 构建系统集成

组件详解

Component Registry (组件注册程序)

主要功能

Log Component (日志组件)

主要功能

使用示例

命令行使用

特性配置

配置映射

启用组件

开发指南

添加新组件

组件开发最佳实践

故障排除

常见问题

依赖关系

component_cn.md 6.2 KB

履歴 Raw