feat(crossterm): allow multiple crossterm versions #1841

joshka · 2025-05-10T19:49:08Z

This commit introduces feature flags to make it possible for widget
library authors to depend on a specific version of crossterm without
causing version conflicts.

The available feature flags are crossterm_0_28 and crossterm_0_29.

This commit introduces feature flags to make it possible for widget library authors to depend on a specific version of crossterm without causing version conflicts. The available feature flags are `crossterm_0_28` and `crossterm_0_29`.

orhun · 2025-05-11T08:31:00Z

ratatui-crossterm/Cargo.toml

+## Enables crossterm 0.28.x
+crossterm_0_28 = ["dep:crossterm_0_28"]
+## Enables crossterm 0.29.x
+crossterm_0_29 = ["dep:crossterm_0_29"]


It might get a bit annoying to add a new feature flag for the each new version of crossterm, even the patches. Or are you thinking of only doing this for the minor versions?

Are we fine with that? If they decide to speed up their release cycle we might end up with so many feature flags. Maybe we can let the upstream know that we are doing this and hear what they think?

It's only necessary for semver incompatible versions (0.x -> 0.x+1). Patch version doesn't matter.
It's also fairly unlikely that crossterm will speed up development IMO. Either way, we can roll with it as needed.
Perhaps we support last 2 versions or something like that. The rationale here is to make it possible for downstream widget crates to support several versions as needed.

Yeah, supporting only the last 2-3 versions sound reasonable to me. We should then update these docs accordingly (we only support blah blah)

I still believe we should adjust this PR a bit to make it easier to add new versions (see my other comments)

orhun · 2025-05-11T08:31:38Z

ratatui-crossterm/src/lib.rs

+//! version of Crossterm is compiled and used by the backend. Attempting to enable none or multiple
+//! `crossterm_xx` features will result in a compile-time error.
+//!
+//! To promote interoperability within the [Ratatui] ecosystem, the selected Crossterm crate is


Suggested change

//! To promote interoperability within the [Ratatui] ecosystem, the selected Crossterm crate is

//! To promote interoperability within the [Ratatui] ecosystem, the selected [Crossterm] crate is

orhun · 2025-05-11T08:31:56Z

ratatui-crossterm/src/lib.rs

+//! `ratatui-crossterm` requires you to specify a version of the [Crossterm] library to be used.
+//! This is managed via feature flags. You **must** enable one, and only one, of the available
+//! `crossterm_xx` features (e.g., `crossterm_28`, `crossterm_29`). These features determine which
+//! version of Crossterm is compiled and used by the backend. Attempting to enable none or multiple


Suggested change

//! version of Crossterm is compiled and used by the backend. Attempting to enable none or multiple

//! version of [Crossterm] is compiled and used by the backend. Attempting to enable none or multiple

We don't need to link every time this is mentioned. It's enough to link it in the first paragraph I think. Sound good?

I'd link every time due to OCD... but sure :D

orhun · 2025-05-11T08:32:17Z

ratatui-crossterm/src/lib.rs

+//!
+//! To promote interoperability within the [Ratatui] ecosystem, the selected Crossterm crate is
+//! re-exported as `ratatui_crossterm::crossterm`. This re-export is essential for authors of widget
+//! libraries or any applications that need to perform direct Crossterm operations while ensuring


Suggested change

//! libraries or any applications that need to perform direct Crossterm operations while ensuring

//! libraries or any applications that need to perform direct [Crossterm] operations while ensuring

orhun · 2025-05-11T08:33:15Z

ratatui-crossterm/src/lib.rs

+//!
+//! For example, if your application's `Cargo.toml` enables the `crossterm_0_29` feature for
+//! `ratatui-crossterm`, then any code using `ratatui_crossterm::crossterm` will refer to the
+//! 0.29 version of Crossterm.


Suggested change

//! 0.29 version of Crossterm.

//! 0.29 version of [Crossterm].

orhun · 2025-05-11T08:34:08Z

xtask/src/commands/check.rs

+            let common_features = [
+                "serde",
+                "underline-color",
+                "scrolling-regions",
+                "unstable",
+                "unstable-backend-writer",
+            ]
+            .join(",");


I think #1820 might help here maybe... Just as a reminder that we should do that :D

I don't think this scenario quite fits into cargo-hack. I may be wrong though. The problem is that the crossterm features are mutually exclusive.

I see... I guess we need to play around with cargo-hack a bit to see how that would work

orhun · 2025-05-11T08:35:03Z

xtask/src/commands/check.rs

+            .join(",");
+
+            // Run `cargo check` on `ratatui-crossterm` with specific crossterm versions
+            for crossterm_feature in ["crossterm_0_28", "crossterm_0_29"] {


I would define a separate constant or variable for the available versions. It makes it easier to just update the array whenever a new crossterm version is out.

Or maybe export it from somewhere such as ratatui_crossterm::AVAILABLE_VERSIONS or something? I'm not sure.

I'm mostly treating xtask as the place where this info is defined. Think of it as a makefile defined in rust. The available versions are not a runtime thing. It maybe makes sense to have a const in the xtask lib, but I think it's clear enough as-is on this. Put another way, you only have to look at this file to understand what the cargo xtask check command will do.

Yup... then maybe let's do a const there? I really don't like the idea of modifying loops directly whenever a new version is out.

orhun · 2025-05-11T08:35:29Z

xtask/src/commands/clippy.rs

+        let clippy_options = ["--", "-D", "warnings"];
+
+        // Run Clippy on `ratatui-crossterm` with `crossterm_0_28` and `crossterm_0_29`
+        for crossterm_feature in ["crossterm_0_28", "crossterm_0_29"] {


Same comment as above.

joshka

Note: this is still a WIP (getting CI to be happy with it)

joshka · 2025-05-11T08:44:24Z

ratatui-crossterm/src/lib.rs

+//! `ratatui-crossterm` requires you to specify a version of the [Crossterm] library to be used.
+//! This is managed via feature flags. You **must** enable one, and only one, of the available
+//! `crossterm_xx` features (e.g., `crossterm_28`, `crossterm_29`). These features determine which
+//! version of Crossterm is compiled and used by the backend. Attempting to enable none or multiple


We don't need to link every time this is mentioned. It's enough to link it in the first paragraph I think. Sound good?

joshka · 2025-05-11T08:48:00Z

xtask/src/commands/check.rs

+            let common_features = [
+                "serde",
+                "underline-color",
+                "scrolling-regions",
+                "unstable",
+                "unstable-backend-writer",
+            ]
+            .join(",");


I don't think this scenario quite fits into cargo-hack. I may be wrong though. The problem is that the crossterm features are mutually exclusive.

joshka · 2025-05-11T08:51:18Z

xtask/src/commands/check.rs

+            .join(",");
+
+            // Run `cargo check` on `ratatui-crossterm` with specific crossterm versions
+            for crossterm_feature in ["crossterm_0_28", "crossterm_0_29"] {


I'm mostly treating xtask as the place where this info is defined. Think of it as a makefile defined in rust. The available versions are not a runtime thing. It maybe makes sense to have a const in the xtask lib, but I think it's clear enough as-is on this. Put another way, you only have to look at this file to understand what the cargo xtask check command will do.

joshka · 2025-05-11T08:51:57Z

xtask/src/commands/clippy.rs

+            // Note that adding --tests or --benches causes clippy to pick up the default features.
+            // I'm not sure why this is the case (JM 2025-05-10).


Any ideas on this?

Never ran into it... But intuitively I'd guess that using those flags will use default features...

joshka requested a review from a team as a code owner May 10, 2025 19:49

joshka mentioned this pull request May 10, 2025

Input Into from KeyEvent seems broken on crossterm 0.29 rhysd/tui-textarea#105

Closed

joshka force-pushed the jm/crossterm-multiple-versions branch 2 times, most recently from a5b5347 to 67d8a4a Compare May 10, 2025 21:05

joshka added 3 commits May 10, 2025 14:10

fix(layout): feature flag cache related types

39aaebc

feat(crossterm): allow multiple crossterm versions

b23dd9b

This commit introduces feature flags to make it possible for widget library authors to depend on a specific version of crossterm without causing version conflicts. The available feature flags are `crossterm_0_28` and `crossterm_0_29`.

fix: cargo xtask clippy for crossterm features

f3d5e7c

joshka force-pushed the jm/crossterm-multiple-versions branch from 67d8a4a to f3d5e7c Compare May 10, 2025 21:12

fix: cargo xtask check for crossterm features

06a5ee3

orhun reviewed May 11, 2025

View reviewed changes

joshka commented May 11, 2025

View reviewed changes

joshka marked this pull request as draft May 11, 2025 08:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(crossterm): allow multiple crossterm versions #1841

feat(crossterm): allow multiple crossterm versions #1841

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	//! To promote interoperability within the [Ratatui] ecosystem, the selected Crossterm crate is
	//! To promote interoperability within the [Ratatui] ecosystem, the selected [Crossterm] crate is

	//! version of Crossterm is compiled and used by the backend. Attempting to enable none or multiple
	//! version of [Crossterm] is compiled and used by the backend. Attempting to enable none or multiple

	//! libraries or any applications that need to perform direct Crossterm operations while ensuring
	//! libraries or any applications that need to perform direct [Crossterm] operations while ensuring

	//! 0.29 version of Crossterm.
	//! 0.29 version of [Crossterm].

		// Note that adding --tests or --benches causes clippy to pick up the default features.
		// I'm not sure why this is the case (JM 2025-05-10).

Uh oh!

feat(crossterm): allow multiple crossterm versions #1841

Are you sure you want to change the base?

feat(crossterm): allow multiple crossterm versions #1841

Uh oh!

Conversation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!