Skip to content

Commit 217c57c

Browse files
orhunjoshka
orhun
and
joshka
authored
refactor: modularize backends (#1508)
Backend code is now moved to `ratatui-crossterm`, `ratatui-termion` and `ratatui-termwiz`. This should be backwards compatible with existing code. Co-authored-by: Josh McKinney <joshka@users.noreply.github.com>
1 parent 3ae6bf1 commit 217c57c

24 files changed

Lines changed: 445 additions & 175 deletions

File tree

‎Cargo.lock‎

Lines changed: 40 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,15 @@
11
[workspace]
22
resolver = "2"
3-
members = ["ratatui", "ratatui-core", "ratatui-widgets", "xtask"]
4-
default-members = ["ratatui", "ratatui-core", "ratatui-widgets"]
3+
members = ["ratatui", "ratatui-*", "xtask"]
4+
default-members = [
5+
"ratatui",
6+
"ratatui-core",
7+
"ratatui-crossterm",
8+
# this is not included as it doesn't compile on windows
9+
# "ratatui-termion",
10+
"ratatui-termwiz",
11+
"ratatui-widgets",
12+
]
513

614
[workspace.package]
715
authors = ["Florian Dehau <work@fdehau.com>", "The Ratatui Developers"]
@@ -12,33 +20,33 @@ keywords = ["tui", "terminal", "dashboard"]
1220
categories = ["command-line-interface"]
1321
readme = "README.md"
1422
license = "MIT"
15-
exclude = [
16-
"assets/*",
17-
".github",
18-
"Makefile.toml",
19-
"CONTRIBUTING.md",
20-
"*.log",
21-
"tags",
22-
]
23+
exclude = ["assets/*", ".github", "Makefile.toml", "CONTRIBUTING.md", "*.log", "tags"]
2324
edition = "2021"
2425
rust-version = "1.74.0"
2526

2627
[workspace.dependencies]
2728
bitflags = "2.6.0"
29+
crossterm = "0.28.1"
2830
document-features = "0.2.7"
2931
indoc = "2.0.5"
3032
instability = "0.3.3"
3133
itertools = "0.13.0"
3234
pretty_assertions = "1.4.1"
3335
ratatui = { path = "ratatui" }
3436
ratatui-core = { path = "ratatui-core" }
37+
ratatui-crossterm = { path = "ratatui-crossterm" }
38+
ratatui-termion = { path = "ratatui-termion" }
39+
ratatui-termwiz = { path = "ratatui-termwiz" }
3540
ratatui-widgets = { path = "ratatui-widgets" }
3641
rstest = "0.23.0"
3742
serde = { version = "1.0.215", features = ["derive"] }
43+
serde_json = "1.0.133"
3844
strum = { version = "0.26.3", features = ["derive"] }
45+
termwiz = { version = "0.22.0" }
3946
unicode-segmentation = "1.12.0"
4047
# See <https://github.com/ratatui/ratatui/issues/1271> for information about why we pin unicode-width
4148
unicode-width = "=0.2.0"
49+
termion = "4.0.0"
4250

4351
# Improve benchmark consistency
4452
[profile.bench]

‎clippy.toml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,15 @@ avoid-breaking-exported-api = false
33
# https://rust-lang.github.io/rust-clippy/master/index.html#/multiple_crate_versions
44
# ratatui -> bitflags v2.3
55
# termwiz -> wezterm-blob-leases -> mac_address -> nix -> bitflags v1.3.2
6+
# (also, memoffset, syn, nix, strsim, windows-sys
67
# crossterm -> all the windows- deps https://github.com/ratatui/ratatui/pull/1064#issuecomment-2078848980
78
allowed-duplicate-crates = [
89
"bitflags",
10+
"memoffset",
11+
"nix",
12+
"strsim",
13+
"syn",
14+
"windows-sys",
915
"windows-targets",
1016
"windows_aarch64_gnullvm",
1117
"windows_aarch64_msvc",

‎ratatui-core/Cargo.toml‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,22 +17,28 @@ exclude.workspace = true
1717
edition.workspace = true
1818
rust-version.workspace = true
1919

20+
[package.metadata.docs.rs]
21+
all-features = true
22+
rustdoc-args = ["--cfg", "docsrs"]
23+
2024
[features]
25+
default = []
26+
2127
## enables conversions from colors in the [`palette`] crate to [`Color`](crate::style::Color).
2228
palette = ["dep:palette"]
2329

2430
## enables the backend code that sets the underline color. Underline color is only supported by
2531
## the Crossterm backend, and is not supported on Windows 7.
2632
underline-color = []
2733

34+
## Use terminal scrolling regions to make some operations less prone to
35+
## flickering. (i.e. Terminal::insert_before).
36+
scrolling-regions = []
37+
2838
## enables serialization and deserialization of style and color types using the [`serde`] crate.
2939
## This is useful if you want to save themes to a file.
3040
serde = ["dep:serde", "bitflags/serde", "compact_str/serde"]
3141

32-
[package.metadata.docs.rs]
33-
all-features = true
34-
rustdoc-args = ["--cfg", "docsrs"]
35-
3642
[dependencies]
3743
bitflags = "2.3"
3844
cassowary = "0.3"
@@ -50,9 +56,13 @@ unicode-truncate = "2"
5056
unicode-width.workspace = true
5157

5258
[dev-dependencies]
53-
rstest.workspace = true
5459
pretty_assertions.workspace = true
55-
serde_json = "1.0.132"
60+
ratatui = { workspace = true, features = ["crossterm", "termwiz"] }
61+
rstest.workspace = true
62+
serde_json.workspace = true
63+
64+
[target.'cfg(not(windows))'.dev-dependencies]
65+
ratatui = { workspace = true, features = ["termion"] }
5666

5767
[lints.clippy]
5868
# we often split up a module into multiple files with the main type in a file named after the

ratatui/src/backend.rs renamed to ratatui-core/src/backend.rs

Lines changed: 7 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
//! Each backend handles raw mode differently, so the behavior may vary depending on the backend
5757
//! being used. Be sure to consult the backend's specific documentation for exact details on how it
5858
//! implements raw mode.
59-
59+
//!
6060
//! # Alternate Screen
6161
//!
6262
//! The alternate screen is a separate buffer that some terminals provide, distinct from the main
@@ -90,15 +90,15 @@
9090
//! backend being used, and developers should consult the specific backend's documentation to
9191
//! understand how it implements mouse capture.
9292
//!
93-
//! [`TermionBackend`]: termion/struct.TermionBackend.html
94-
//! [`Terminal`]: crate::terminal::Terminal
95-
//! [`TermionBackend`]: termion/struct.TermionBackend.html
93+
//! [`CrosstermBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.CrosstermBackend.html
94+
//! [`TermionBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermionBackend.html
95+
//! [`TermwizBackend`]: https://docs.rs/ratatui/latest/ratatui/backend/struct.TermwizBackend.html
96+
//! [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
9697
//! [Crossterm]: https://crates.io/crates/crossterm
9798
//! [Termion]: https://crates.io/crates/termion
9899
//! [Termwiz]: https://crates.io/crates/termwiz
99100
//! [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md
100-
//! [Backend Comparison]:
101-
//! https://ratatui.rs/concepts/backends/comparison/
101+
//! [Backend Comparison]: https://ratatui.rs/concepts/backends/comparison/
102102
//! [Ratatui Website]: https://ratatui.rs
103103
use std::io;
104104

@@ -109,21 +109,6 @@ use crate::{
109109
layout::{Position, Size},
110110
};
111111

112-
#[cfg(feature = "crossterm")]
113-
mod crossterm;
114-
#[cfg(feature = "crossterm")]
115-
pub use self::crossterm::{CrosstermBackend, FromCrossterm, IntoCrossterm};
116-
117-
#[cfg(all(not(windows), feature = "termion"))]
118-
mod termion;
119-
#[cfg(all(not(windows), feature = "termion"))]
120-
pub use self::termion::{FromTermion, IntoTermion, TermionBackend};
121-
122-
#[cfg(feature = "termwiz")]
123-
mod termwiz;
124-
#[cfg(feature = "termwiz")]
125-
pub use self::termwiz::{FromTermwiz, IntoTermwiz, TermwizBackend};
126-
127112
mod test;
128113
pub use self::test::TestBackend;
129114

@@ -162,7 +147,7 @@ pub struct WindowSize {
162147
/// Most applications should not need to interact with the `Backend` trait directly as the
163148
/// [`Terminal`] struct provides a higher level interface for interacting with the terminal.
164149
///
165-
/// [`Terminal`]: crate::terminal::Terminal
150+
/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
166151
pub trait Backend {
167152
/// Draw the given content to the terminal screen.
168153
///

ratatui/src/backend/test.rs renamed to ratatui-core/src/backend/test.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -144,7 +144,7 @@ impl TestBackend {
144144
#[track_caller]
145145
pub fn assert_buffer(&self, expected: &Buffer) {
146146
// TODO: use assert_eq!()
147-
ratatui_core::assert_buffer_eq!(&self.buffer, expected);
147+
crate::assert_buffer_eq!(&self.buffer, expected);
148148
}
149149

150150
/// Asserts that the `TestBackend`'s scrollback buffer is equal to the expected buffer.

‎ratatui-core/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
//!
3939
//! This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details.
4040
41+
pub mod backend;
4142
pub mod buffer;
4243
pub mod layout;
4344
pub mod style;

‎ratatui-crossterm/Cargo.toml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[package]
2+
name = "ratatui-crossterm"
3+
version = "0.1.0"
4+
description = "Crossterm backend for the Ratatui Terminal UI library."
5+
documentation = "https://docs.rs/ratatui-crossterm/"
6+
readme = "README.md"
7+
authors.workspace = true
8+
repository.workspace = true
9+
homepage.workspace = true
10+
keywords.workspace = true
11+
categories.workspace = true
12+
license.workspace = true
13+
exclude.workspace = true
14+
edition.workspace = true
15+
rust-version.workspace = true
16+
17+
[features]
18+
default = ["underline-color"]
19+
20+
## enables the backend code that sets the underline color.
21+
## Underline color is only supported by the [`CrosstermBackend`](backend::CrosstermBackend) backend,
22+
## and is not supported on Windows 7.
23+
underline-color = []
24+
25+
## Use terminal scrolling regions to make Terminal::insert_before less prone to flickering.
26+
scrolling-regions = ["ratatui-core/scrolling-regions"]
27+
28+
#! The following features are unstable and may change in the future:
29+
30+
## Enable all unstable features.
31+
unstable = ["unstable-backend-writer"]
32+
33+
## Enables getting access to backends' writers.
34+
unstable-backend-writer = []
35+
36+
37+
[dependencies]
38+
crossterm.workspace = true
39+
document-features = { workspace = true, optional = true }
40+
instability.workspace = true
41+
ratatui-core = { workspace = true }
42+
43+
[dev-dependencies]
44+
ratatui = { workspace = true, features = ["crossterm"] }
45+
rstest.workspace = true

‎ratatui-crossterm/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Ratatui-crossterm
2+
3+
<!-- cargo-rdme start -->
4+
5+
This module provides the [`CrosstermBackend`] implementation for the [`Backend`] trait. It uses
6+
the [Crossterm] crate to interact with the terminal.
7+
8+
[Crossterm]: https://crates.io/crates/crossterm
9+
10+
<!-- cargo-rdme end -->

ratatui/src/backend/crossterm.rs renamed to ratatui-crossterm/src/lib.rs

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,21 @@
1+
// show the feature flags in the generated documentation
2+
#![cfg_attr(docsrs, feature(doc_cfg))]
3+
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
4+
#![doc(
5+
html_logo_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/logo.png",
6+
html_favicon_url = "https://raw.githubusercontent.com/ratatui/ratatui/main/assets/favicon.ico"
7+
)]
8+
#![warn(missing_docs)]
19
//! This module provides the [`CrosstermBackend`] implementation for the [`Backend`] trait. It uses
210
//! the [Crossterm] crate to interact with the terminal.
311
//!
412
//! [Crossterm]: https://crates.io/crates/crossterm
13+
#![cfg_attr(feature = "document-features", doc = "\n## Features")]
14+
#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
15+
516
use std::io::{self, Write};
617

18+
pub use crossterm;
719
#[cfg(feature = "underline-color")]
820
use crossterm::style::SetUnderlineColor;
921
use crossterm::{
@@ -16,8 +28,7 @@ use crossterm::{
1628
},
1729
terminal::{self, Clear},
1830
};
19-
20-
use crate::{
31+
use ratatui_core::{
2132
backend::{Backend, ClearType, WindowSize},
2233
buffer::Cell,
2334
layout::{Position, Size},
@@ -74,8 +85,8 @@ use crate::{
7485
/// for more details on raw mode and alternate screen.
7586
///
7687
/// [`Write`]: std::io::Write
77-
/// [`Terminal`]: crate::terminal::Terminal
78-
/// [`backend`]: crate::backend
88+
/// [`Terminal`]: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
89+
/// [`backend`]: ratatui_core::backend
7990
/// [Crossterm]: https://crates.io/crates/crossterm
8091
/// [Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui/examples/README.md
8192
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]

0 commit comments

Comments
 (0)