/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).

Primary LanguageRustMIT LicenseMIT

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.

example 1 example 2 example 3 example 4

References

Implementation is based on:

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