rt-thread/components/rust/docs/3.components/component_cn.md

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 是整个架构的核心，负责统一管理所有组件的注册。

主要功能

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

Log Component (日志组件)

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

主要功能

1. 多级别日志: 支持 INFO、WARN、ERROR、DEBUG、TRACE 等日志级别
2. 命令行接口: 提供 log_info、log_warn、log_error 等命令
3. 条件编译: 只在 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

开发指南

添加新组件

1. 创建组件目录

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

2. 创建 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 = []
   

3. 实现组件功能

   // src/new.rs
   // 新组件的实现代码
   
   // src/lib.rs
   #![no_std]
   // 导出需要的库
   

4. 更新特性配置

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

5. 更新注册程序

   # 在 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");
       }
       // ... 其他组件 ...
   }
   

组件开发最佳实践

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

故障排除

常见问题

1. 编译失败

   • 检查 Rust 工具链是否正确安装
   • 确认目标架构 (如 riscv64imac-unknown-none-elf) 已安装
   • 检查依赖路径是否正确

2. 特性未启用

   • 确认 RT-Thread 配置中已设置相应的宏定义
   • 检查 feature_config_component.py 中的映射配置
   • 查看构建日志中的特性启用信息

3. 链接错误

   • 确认所有依赖组件都已正确构建
   • 检查 Cargo.toml 中的依赖配置
   • 验证库文件路径和名称

依赖关系

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