diff options
| author | bernard <[email protected]> | 2025-12-13 21:42:29 +0800 |
|---|---|---|
| committer | R b b666 <[email protected]> | 2025-12-15 12:50:49 +0800 |
| commit | 4f154d8207be7320be07477fe3857523b1704977 (patch) | |
| tree | d32fa76e74dccef9a58c7b5d54d10a2f4f54c4d6 /components/rust/docs/3.components/component.md | |
| parent | 3c459aecea7135f96d9ebd291d276a6e18fd97c7 (diff) | |
[rust] Tidy core defaults and migrate docs to README
Diffstat (limited to 'components/rust/docs/3.components/component.md')
| -rw-r--r-- | components/rust/docs/3.components/component.md | 226 |
1 files changed, 0 insertions, 226 deletions
diff --git a/components/rust/docs/3.components/component.md b/components/rust/docs/3.components/component.md deleted file mode 100644 index df1f7126ee..0000000000 --- a/components/rust/docs/3.components/component.md +++ /dev/null @@ -1,226 +0,0 @@ -# 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 |
