Adding Rust Language Support for RT-Thread #10910

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
+```