diff options
Diffstat (limited to 'components/rust/docs/3.components')
| -rw-r--r-- | components/rust/docs/3.components/component.md | 226 | ||||
| -rw-r--r-- | components/rust/docs/3.components/component_cn.md | 227 |
2 files changed, 453 insertions, 0 deletions
diff --git a/components/rust/docs/3.components/component.md b/components/rust/docs/3.components/component.md new file mode 100644 index 0000000000..df1f7126ee --- /dev/null +++ b/components/rust/docs/3.components/component.md @@ -0,0 +1,226 @@ +# Example Component - RT-Thread Rust Component Example + +## Overview + +`example_component` is a Rust component example based on RT-Thread, demonstrating how to implement, register, and manage Rust components in RT-Thread systems. This project adopts a unified component registration architecture that avoids component duplicate registration issues and supports conditional compilation based on RT-Thread configuration. + +## Project Structure + +``` +example_component/ +├── SConscript # SCons build script +├── component_registry/ # Unified component registry +│ ├── Cargo.toml # Registry configuration +│ └── src/ +│ └── lib.rs # Registry implementation +├── log/ # Log component example +│ ├── Cargo.toml # Log component configuration +│ └── src/ +│ ├── lib.rs # Log component implementation +│ └── logging.rs # Logging functionality module +└── tools/ # Build tools + ├── build_component.py # Component build tool + └── feature_config_component.py # Feature configuration +``` + +## Core Features + +### 1. Unified Component Registration Architecture + +- **Avoid Duplicate Registration**: Unified management of all component registrations through `component_registry`, avoiding conflicts caused by multiple component duplicate registrations +- **Conditional Compilation Support**: Selectively compile and register components based on RT-Thread configuration +- **Modular Design**: Each component is implemented independently and managed uniformly through the registry + +### 2. Feature Configuration System + +- **Based on RT-Thread Configuration**: Feature enablement is entirely based on RT-Thread configuration items, requiring no additional configuration +- **Automatic Feature Mapping**: Build system automatically maps RT-Thread configuration to Rust features +- **Dependency Checking**: Automatically checks component dependencies to ensure build consistency + +### 3. Build System Integration + +- **SCons Integration**: Fully integrated with RT-Thread's SCons build system +- **Incremental Build**: Supports clean and incremental builds +- **Cross Compilation**: Supports cross-compilation for target architectures like RISC-V + +## Component Details + +### Component Registry + +`component_registry` is the core of the entire architecture, responsible for unified management of all component registrations. + +#### Main Functions + +1. **Unified Entry Point**: Provides `rust_component_registry` as the unified registration entry for all components +2. **Conditional Compilation**: Only includes and registers corresponding components when respective features are enabled +3. **Avoid Conflicts**: Ensures each component is registered only once + +### Log Component + +The `log` component provides Rust-style logging functionality, including multiple log levels and command-line interface. + +#### Main Functions + +1. **Multi-level Logging**: Supports INFO, WARN, ERROR, DEBUG, TRACE and other log levels +2. **Command-line Interface**: Provides commands like `log_info`, `log_warn`, `log_error` +3. **Conditional Compilation**: Only compiles when `enable-log` feature is enabled + +#### Usage Examples + +```rust +// Using log macros in code +info!("This is an info log"); +warn!("This is a warning log"); +error!("This is an error log"); +``` + +#### Command-line Usage + +```bash +# Using in RT-Thread command line +msh> log_info # Print info log +msh> log_warn # Print warning log +msh> log_error # Print error log +``` + +## Feature Configuration + +### Configuration Mapping + +The mapping from RT-Thread configuration to Rust features is defined in `tools/feature_config_component.py`: + +```python +CONFIG_COMPONENT_FEATURE_MAP = { + 'RUST_LOG_COMPONENT': { + 'feature': 'enable-log', + 'dependency': 'em_component_log', + 'description': 'Enable Rust log component integration' + } +} +``` + +### Enabling Components + +To enable the log component, set in RT-Thread configuration: + +```c +// Set through menuconfig +Enable Rust component support -> Auto-initialize Rust log component +``` + +## Development Guide + +### Adding New Components + +1. **Create Component Directory** + ```bash + cargo new --lib example_component/new_component + cd example_component/new_component + ``` + +2. **Create Cargo.toml** + ```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. **Implement Component Functionality** + ```rust + // src/new.rs + // New component implementation code + + // src/lib.rs + #![no_std] + // Export required libraries + ``` + +4. **Update Feature Configuration** + ```python + # Add to tools/feature_config_component.py + CONFIG_COMPONENT_FEATURE_MAP = { + # ... existing configuration ... + 'RUST_NEW_COMPONENT': { + 'feature': 'enable-new', + 'dependency': 'em_component_new', + 'description': 'Enable new component integration' + } + } + ``` + +5. **Update Registry** + ```toml + # Add to component_registry/Cargo.toml + [dependencies] + em_component_new = { path = "../new_component", optional = true } + + [features] + enable-new = ["em_component_new", "em_component_new/enable-new"] + ``` + + ```rust + // Register in 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"); + } + // ... other components ... + } + ``` + +### Component Development Best Practices + +1. **Use Conditional Compilation**: All functionality should be wrapped with `#[cfg(feature = "...")]` +2. **Avoid Direct Registration**: Don't use component registration macros directly in components, let `component_registry` manage uniformly +3. **Provide Command Interface**: Provide command-line interfaces for component functionality for easy testing and usage +4. **Complete Documentation**: Provide detailed documentation and usage examples for each component + +## Troubleshooting + +### Common Issues + +1. **Compilation Failure** + - Check if Rust toolchain is correctly installed + - Confirm target architecture (e.g., `riscv64imac-unknown-none-elf`) is installed + - Check if dependency paths are correct + +2. **Features Not Enabled** + - Confirm corresponding macro definitions are set in RT-Thread configuration + - Check mapping configuration in `feature_config_component.py` + - Review feature enablement information in build logs + +3. **Linking Errors** + - Confirm all dependent components are correctly built + - Check dependency configuration in `Cargo.toml` + - Verify library file paths and names + +## Dependency Relationships + +``` +RT-Thread Config + ↓ +Feature Mapping + ↓ +Rust Features + ↓ +Component Registry ← Individual Components + ↓ +RT-Thread System +```
\ No newline at end of file diff --git a/components/rust/docs/3.components/component_cn.md b/components/rust/docs/3.components/component_cn.md new file mode 100644 index 0000000000..ff48fc859a --- /dev/null +++ b/components/rust/docs/3.components/component_cn.md @@ -0,0 +1,227 @@ +# 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` 特性启用时编译 + +#### 使用示例 + +```rust +// 在代码中使用日志宏 +info!("这是一条信息日志"); +warn!("这是一条警告日志"); +error!("这是一条错误日志"); +``` + +#### 命令行使用 + +```bash +# 在 RT-Thread 命令行中使用 +msh> log_info # 打印信息日志 +msh> log_warn # 打印警告日志 +msh> log_error # 打印错误日志 +``` + +## 特性配置 + +### 配置映射 + +在 `tools/feature_config_component.py` 中定义了 RT-Thread 配置到 Rust 特性的映射： + +```python +CONFIG_COMPONENT_FEATURE_MAP = { + 'RUST_LOG_COMPONENT': { + 'feature': 'enable-log', + 'dependency': 'em_component_log', + 'description': 'Enable Rust log component integration' + } +} +``` + +### 启用组件 + +要启用日志组件，需要在 RT-Thread 配置中设置： + +```c +// 通过 menuconfig 设置 +Enable Rust component support -> Auto-initialize Rust log component +``` + +## 开发指南 + +### 添加新组件 + +1. **创建组件目录** + ```bash + cargo new --lib example_component/new_component + cd example_component/new_component + ``` + +2. **创建 Cargo.toml** + ```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. **实现组件功能** + ```rust + // src/new.rs + // 新组件的实现代码 + + // src/lib.rs + #![no_std] + // 导出需要的库 + ``` + +4. **更新特性配置** + ```python + # 在 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. **更新注册程序** + ```toml + # 在 component_registry/Cargo.toml 中添加 + [dependencies] + em_component_new = { path = "../new_component", optional = true } + + [features] + enable-new = ["em_component_new", "em_component_new/enable-new"] + ``` + + ```rust + // 在 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 +``` |