marmidr / rtwins

RTWins is a Rust library designed for easy creation of terminal applications, targetting non-os, resource-constrained devices, like bare metal Cortex-M3 devices (64KiB Flash or more).

RTWins in brief

RTWins is a Rust library designed for easy creation of terminal applications, targetting non-os, resource-constrained devices, like bare metal Cortex-M3 devices (128KiB Flash or more).

It provides basic facilities required by interactive applications, such as screen and cursor management, keyboard input, keymaps, color codes.

References

Implementation is based on:

• https://github.com/marmidr/twins
• Wiki: reference color tables for different terminals

Primary goals

• text properties
  • foreground and background color codes
  • attributes (bold, inversion)
• operations
  • clear screen
  • go to home
  • go to location
• reading input
  • regular characters (a..z)
  • control codes (Up/Down, Del, Ctrl, Home, ...)
• buffered terminal output
• platform abstraction layer (PAL) to ease porting
• command line interface with history (CLI)
• no_std

Secondary goals

• widgets (controls) to implement
  • window
  • panel
  • static label / led
  • check box
  • text edit (text/number)
  • radio button
  • page control
  • progress bar
  • list box
  • combo box
  • scrollable text box
  • custom widget base
  • scrollbar
  • horizontal page control
  • popup windows
  • layers - to control visibility of groups of widgets
  • password input
• navigation
  • widgets navigation by Tab/Esc key
  • render focused widget state
  • blinking cursor instead of inversed colors
  • select widget by mouse
• notifications
  • notify event per widget type (button clicked, checkbox toggled)
• color theme for window
• keyboard handler returns if key was handled by active widget
• support for mouse click
• double-width character support (emoticons 😁)
• multiline solid button

---

Prerequisites

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

just - convenient command runner

Package comes with the Justfile - make-like collection of useful commands.

https://github.com/casey/just#packages

Build and run TUI demo

# full demo
cargo r --example demo_full
# mini demo
cargo r --example demo_mini

# full demo with slow_flush enabled:
cargo r --features=slow_flush --example demo_full
# using justfile
just r

How to build and run unit tests

# standard test runner
cargo t
# test using nextest (https://nexte.st/)
just nx

---

Test coverage - grcov

Coverage generation tools grcov is provided by Mozzilla.

First, nightly version of Rust is needed:

rustup show
rustup toolchain install nightly
rustup show
rustup default nightly

Now install dependencies:

cargo install grcov
rustup component add llvm-tools-preview

Build and test

export LLVM_PROFILE_FILE="your_name-%p-%m.profraw"
export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
export RUSTDOCFLAGS="-Cpanic=abort"
cargo +nightly test
grcov . --source-dir . --binary-path ./target/debug/ -t html --branch --ignore-not-existing --ignore "tests/*" -o ./target/debug/coverage/

Open the target/debug/coverage/index.html to see the report

---

Test coverage - tarpaulin (only Linux +x86)

https://lib.rs/crates/cargo-tarpaulin

cargo install cargo-tarpaulin
cargo tarpaulin --out Html --skip-clean

Cons:

• runs cargo clean every time you switch between cargo test and cargo tarpaulin
• uses source files to generate html report details on-the-fly
• --count is not working
• no branch coverage

---

nextest - faster test runner for Rust

cargo-nextest, a next-generation test runner for Rust projects

https://nexte.st/book/pre-built-binaries.html

expand - macro expansion tool

Install from sources:

cargo install cargo-expand
just expand-lib debug_trace
just expand-demo tui_msgbox_def

bloat - what takes most of the space in your executable

https://github.com/RazrFalcon/cargo-bloat

cargo install cargo-bloat
just bloat-lib
just bloat-demo

audit - performs vulnerabilities check

https://crates.io/crates/cargo-audit

# cargo install cargo-audit - auto installed by `just audit`
just audit