Tracking issue: `no_std` Ratatui

[j-g00da]

Previously discussed here: #1746

Problem

Currently, due to the usage of std in ratatui, its usage on embedded devices is very limited, mostly to Espressif’s MCUs based on Xtensa (nightly) and RISC-V architectures. It would be beneficial to be able to compile at least ratatui-core (and ratatui-widgets in the future) for bare-metal targets. I am convinced that it would be possible to run ratatui on many more modern MCUs such as STM32H7XX.

Solution

Convert first ratatui-core, and later ratatui-widgets to no_std implementations, add std feature flag.

Plan

Important assumptions

1. We should favor alloc and core instead of std where possible and add linter rules for that. This is a simple non-breaking change and should be the first step in moving towards no_std support.
2. All cargo features should be additive - we should use std feature instead of no_std and list it in every other feature that requires std.

Analysis of the current state of the codebase - ratatui-core

std usages

| 🟢 - in core | 🟡 - in alloc
 | 🔴 - requires std |

• 🟢 std::fmt::{Write, Display, Result, Formatter, Debug}
• 🟡 std::borrow::Cow
• 🟢 std::str::{from_utf8, FromStr}
• 🟢 std::ops::{Index, IndexMut, Add, Range}
• 🟢 std::cell::{RefCell}
• 🔴 std::collections::HashMap - hashbrown::HashMap is a no_std drop-in replacement
• 🟢 std::iter::*
• 🔴 std::io::Result
• 🟢 std::num::NonZeroUsize
• 🟡 std::rc::Rc
• 🟢 std::cmp::{max, min}
• 🟡 std::vec::IntoIter
• 🟢 std::slice::{Iter, IterMut}
• 🟢 std::error::Error

Dependencies

| ✅ - no_std | ❌ - uses std |

• ✅ bitflags
• ❌ cassowary - not updated since 2017, has no dependencies, probably safe to fork and do minimal changes to make it no_std-compatible, or do the same with @joshka's kasuari fork
• ✅ compact_str

• ✅ indoc

• ✅ itertools
• ✅ lru
• ✅ strum
• ✅ thiserror
• ✅ unicode-segmentation
• ✅ unicode-truncate
• ✅ unicode-width


Optional dependencies

• ✅ anstyle
• ❌ document-features - only matters for docs
• ✅ palette
• ✅ serde

Tasks

✅ Core Tasks Stage 0 - preparations

• feat(no_std): remove redundant std usages in ratatui-core #1753
• chore(lint): add std instead of core/alloc lints to ratatui-core #1759

External tasks

• feat: make the crate no_std kasuari#2

✅ Core Tasks Stage 1 - no_std ratatui-core

• build(deps): use kasuari instead of cassowary #1758
• refactor(no_std): Make usages of std explicit in ratatui-core. #1782
• feat(no_std)!: replace Backend's io::Error usages with associated Error type #1778
• feat(no_std)!: option to disable layout cache for no_std compatibility #1795
• feat(no_std)!: make ratatui compatible with #![no_std] #1794
• feat(no_std)!: make TestBackend::Error Infallible #1823

🏗️ Core Tasks Stage 2 - no_std ratatui-widgets & no_std backends

• feat(no_std): remove redundant std usages in ratatui-widgets #1762
• chore(lint): add std instead of core/alloc lints to ratatui-widgets #1763
• feat(no_std): make ratatui-widgets no_std #1779

External tasks

• feat(no_std): use core/alloc instead of std where possible j-g00da/mousefood#39
• chore(lint): add std instead of core/alloc lints j-g00da/mousefood#45
• Depend on ratatui-core instead of ratatui j-g00da/mousefood#36
• Make mousefood work with #![no_std] j-g00da/mousefood#59

🏗️ Related bugfixes and other tasks

• feat(error)!: introduce ratatui_core::error::Error #1817
• fix(no_std): provide f64 polyfills for no_std compatibility #1840
• fix(layout-cache): import NonZeroUsize only when layout-cache is enabled #1839
• fix(no_std): propagate std feature flag to dependencies #1838
• chore: move time to dev-dependencies #1835
• chore(widgets): move crossterm to dev-dependencies #1834
• fix(no_std): final patches needed for no_std #1833
• chore(breaking-changes): add details to no_std-related breaking changes #1828
• fix(layout): feature flag cache related types #1842
• feat(no_std): make the crate no_std-compatible joshka/line-clipping#1
• feat(no_std): option to disable std kasuari#16
• Add test for *-unknown-none build #1843
• build(deps): bump kasuari and line-clipping #1844
• feat(no_std): make ratatui-macros no-std #1865

[joshka]

std::rc::Rc is there because the layout might return cached layout values because recomputing the math can be slow.

I think I'd go with using kasuari instead of making another fork.

std::io::Result seems like it's posssibly going to be the largest problem as this is used pretty much everywhere. That said, introducing our own error type could make a good reason to version bump ratatui-core down the line. (I.e. release ratatui-core 0.1, and work towards the no-std in 0.2)

[j-g00da]

When adding std feature, should we also add alloc in case we wanted to add no-global-allocator support in the future?

[features]
default = ["crossterm"]
alloc = []
std = ["alloc"]
# some feature that requires std
crossterm = ["std",  "dep:ratatui-crossterm"]
# some no_std feature that requires a global allocator
widget-calendar = ["alloc", "ratatui-widgets/alloc", "ratatui-widgets/calendar", "dep:time"]

[joshka]

You're more of an expert here on that question. Are there other crates that do this one way or another?

[j-g00da]

https://github.com/rust-bakery/nom/blob/main/Cargo.toml

hashbrown also does something similar.

[joshka]

hashbrown also does something similar.

Sounds like a reasonable example to follow :)

[j-g00da]

I withdraw from this - I was wrong.

Anyway, after thinking that through, I don't think we really need alloc feature, and even if we wanted to add it later on, it wouldn't be a breaking change.

Let's go with just std for now.

Should we make initial, non-breaking changes in widgets already for 0.30 release?

[joshka]

Should we make initial, non-breaking changes in widgets already for 0.30 release?

Yep

One thing I did have a bit of a concern about was whether the std::* to core::* are generally type aliases or different types altogether. If they're different types with the same name, then we likely actually need to make a note of these in the breaking changes docs. If they're the same type then we likely don't

[j-g00da]

They are the same types, std re-exports core and alloc.

[j-g00da]

The layout cache depends on thread_local macro. We have to decide what to do about it.
Conditionally compile an alternative implementation, when std feature is disabled?

This compiles with #![no_std], but I haven't tested it on any device yet.
Requires two new dependencies - critical_section and once_cell.

use critical_section::Mutex;
use once_cell::sync::Lazy;

static LAYOUT_CACHE: Lazy<Mutex<RefCell<Cache>>> = Lazy::new(|| {
    Mutex::new(RefCell::new(LruCache::new(NonZeroUsize::new(Layout::DEFAULT_CACHE_SIZE).unwrap())))
});

Layout::split_with_spacers would look like this:

pub fn split_with_spacers(&self, area: Rect) -> (Segments, Spacers) {
    critical_section::with(|cs| {
        let mut cache = LAYOUT_CACHE.borrow_ref_mut(cs);

        let key = (area, self.clone());
        cache.get_or_insert(key, || self.try_split(area).expect("failed to split")).clone()
    })
}

[joshka]

I think this got fully implemented. Was there anything else on this that needed finishing @j-g00da?

[j-g00da]

It's all done, closing :)