Building from Source & Feature Flags
Relevant source files
The following files were used as context for generating this wiki page:
ComChan is designed as a modular serial monitor and plotter that can be customized at compile-time via Rust feature flags. Users can build the project using standard Cargo commands or through the integrated Grimoire task runner, which provides an interactive interface for selecting optional capabilities like Bluetooth Low Energy (BLE) or hardware-accelerated 3D rendering.
The build system focuses on performance and binary size, utilizing Link Time Optimization (LTO) and specific release profiles to ensure a "blazingly fast" experience on embedded development machines.
Sources: README.md:1-15, Cargo.toml:1-15
Build Prerequisites and Environment
Building ComChan requires the Rust toolchain (Edition 2024). The project is organized as a workspace containing the main comchan crate and a local ratatui-wireframe widget crate.
Release Profile Optimization
To minimize binary size and maximize performance, the project uses a specialized [profile.release] configuration:
| Setting | Value | Description |
|---|---|---|
opt-level | "z" | Optimizes for binary size. |
lto | true | Enables Link Time Optimization to drop dead code. |
codegen-units | 1 | Compiles in one chunk for better optimization. |
strip | true | Automatically strips symbols from the binary. |
panic | "abort" | Removes stack-unwinding infrastructure. |
Sources: Cargo.toml:17-57, CHANGELOG.md:38-38
Compilation Methods
Standard Cargo Build
The project can be built from source using standard git and cargo workflows. By default, optional features are disabled to ensure compatibility with environments lacking specific dependencies (like libudev or BLE stacks).
# Clone and build with all features
git clone https://github.com/Vaishnav-Sabari-Girish/ComChan.git
cd ComChan
cargo build --release --features ble,ratty
Sources: README.md:95-106, Cargo.toml:17-21
Grimoire Task Runner
ComChan includes a Grimoire.toml configuration, allowing users to use the grim tool for interactive builds. This eliminates the need to remember specific feature flag names.
The diagram shows the interactive flow when using the Grimoire task runner to compile the project.
Sources: Grimoire.toml:1-55, README.md:110-130
Feature Flags Reference
Feature flags control the inclusion of heavy dependencies and specialized rendering engines.
| Feature | Dependency | Description |
|---|---|---|
default | None | Base serial monitor and Braille-based 2D/3D plotting. |
ratty | ratatui-ratty | Hardware-accelerated 3D rendering using the Ratty Graphics Protocol. |
ble | btleplug, tokio, uuid | Bluetooth Low Energy support for Nordic UART Service (NUS) streaming. |
std | ratatui/layout-cache | Enables standard library features in ratatui-wireframe (Default). |
Feature Interaction in Code
In src/plotter.rs, the ratty feature is used to conditionally compile the GPU-accelerated 3D engine. If the feature is absent, the system falls back to a CPU-rendered Braille engine.
#[cfg(feature = "ratty")]
use ratatui_ratty::{ObjectFormat, RattyGraphic, RattyGraphicSettings};
// Example of conditional initialization
#[cfg(feature = "ratty")]
let ratty_engines = {
// Initialization for hardware-accelerated 3D
};
Sources: Cargo.toml:17-21, crates/ratatui-wireframe/Cargo.toml:18-21, src/plotter.rs:172-225
Dependency Management
The project balances feature-richness with binary efficiency by marking heavy libraries as optional.
This diagram illustrates how optional features pull in external dependencies while maintaining a slim core.
Sources: Cargo.toml:23-52, crates/ratatui-wireframe/Cargo.toml:12-16
Summary
Building ComChan from source offers the highest level of flexibility through its feature-flagged architecture. By leveraging the release profile optimizations defined in Cargo.toml and the interactive task management provided by Grimoire.toml, developers can produce a highly optimized binary tailored to their specific hardware needs, whether they require wireless BLE telemetry or advanced hardware-accelerated 3D visualizations.
Sources: Cargo.toml:59-75, README.md:135-155