Taskbar progress reporting via ANSI codes

[Gordon01]

trafficstars

What does this PR try to resolve?

A few traminal emulators support progress output to Windows taskbar. winget uses this to show install progress.

Notably, Windows Terminal recently (2020) added support for ANSI codes specified in ConEmu (another terminal emulator for Windows) documentation. Also, in "Learn Windows".

I've found the previous attempt to add this feature: https://github.com/rust-lang/cargo/pull/11436

As per @weihanglo's request, I've added the config option to enable/disable this feature. It's enabled on Windows by default.

Fixes #11432

How should we test and review this PR?

Run cargo build in Windows Terminal with configuration option term.progress.taskbar set to true.

Not sure

• [ ] Should all the code be #[cfg(windows)]? Probably no, because feature is also usable in WSL.
• [ ] If Ctrl+C is pressed, a progressbar will stay in a last state forever (shown in the ConEmu video). winget is also behaves like alike. I've experimented with ctrl_c handler and it's totally fixable.
• [ ] Enabled is a sensible default for WSL because it works on linux builds in Windows Terminal too
• [ ] Downloading stage may produce unpleasant blinking due to a rapid 0-100 changes

TLDR

• An term.progress.taskbar option with bool type is added
• On Windows it is set to true when unspecified
• If enabled together with cargo progress bar feature, emits ANSI escape codes to draw a progress bar on taskbar on supported terminal

Videos

https://github.com/user-attachments/assets/48bb648a-e819-490e-b3ac-3502bc5f2f3a

https://github.com/user-attachments/assets/1d7ddf7a-34dd-4db1-b654-e64d7170798e

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @epage (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[weihanglo]

@rustbot author

[Gordon01]

Hello, Ed, thank you for the review and sorry for the late feedback. It's been a lot of work lately.

[epage]

Hello, Ed, thank you for the review and sorry for the late feedback. It's been a lot of work lately.

Understandable!

[epage]

This is looking really great and making me jealous that my terminal doesn't support it!

[Gordon01]

This is looking really great and making me jealous that my terminal doesn't support it!

Happy to hear! With the help of your feedback it works better than my first iteration.

I've cleaned up the code a little it the latest commit. TaskbarProgress::from_config() now has terminal detection and config logic. new() is #[cfg(test)] now. And also added a test that the disabled taskbar doesn't output anything.

I think it looks like it's finished.

[Gordon01]

@rustbot review

[Gordon01]

Hello, @epage and everyone interested. Hope, you're well!

I have a good news! The progress in standartisation of the sequence is going well. Soon it's gonna be supported by systemd and GNOME vte. Here is the message from Christian Persch:

So my conclusion after reading through this issue, the windows terminal issue/pr, and conemu implementation, is that while this API has flaws and might be improved, it's reasonably widely implemented, and small enough (and the flaws small enough) so as to make it not worthwhile to try to invent yet another protocol for this. Therefore I'm going to commit a patch to support OSC 9 ; 4 to vte (plus hook it up in the test app). I've changed it a bit since the last wip/progress branch; please check and test if this still meets the requirements. The parser at least should fully copy conemu behaviour.

And, cosequently support to Ptyxis was added.

From Lennart Poettering:

Since a while systemd has been showing nice terminal progress bars when doing certain slow operations (for example, when systemd-repart initializes a disk). With v257 we go one step further with this. Whenever we show the progress bar we'll now also issue certain terminal ANSI sequences that tell your terminal emulator that a slow operation is going on and what the progress currently is.

And the bug in kitty about the conflict with their OSC 9 implementation was fixed here. Also in foot.

So, to sum it up, Ed, it looks like you will get the support in your terminal earlier than you anticipated.

[weihanglo]

Thank you for driving this!

I use Kitty so may gain nothing, but still a great feature!

[epage]

@rfcbot fcp merge

In terms of stability, this adds a new config field

[term]
progress.taskbar = true # whether cargo reports progress to terminal emulator

Like with hyperlinks and unicode, it is auto-detect by default and can be explicitly turned on/off.

For rendering, this ANSI escape code is supported by at least

• ConEmu
• Windows Terminal
• GNOME vte / Ptyxis (not added to cargo's auto-detection yet)

For emitting, this ANSI escape code is supported by at least

• systemd

In the current implementation, if the user hits ctrl-c, then nothing will remove the taskbar status. We could add a ctrl-c handler but I'm always hesitant about those and would prefer to see if we can get away without it. It also sounds like other existing programs don't add a ctrl-c handler for this.

[rfcbot]

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

• [x] @Eh2406
• [x] @Muscraft
• [x] @Rustin170506
• [x] @arlosi
• [x] @ehuss
• [x] @epage
• [x] @joshtriplett
• [x] @weihanglo

Concerns:

• ~~config-name~~ resolved by https://github.com/rust-lang/cargo/pull/14615#issuecomment-2679650746
• ~~config-name-part-2~~ resolved by https://github.com/rust-lang/cargo/pull/14615#issuecomment-2710839334

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

:bell: This is now entering its final comment period, as per the review above. :bell:

[joshtriplett]

@rfcbot reviewed @rfcbot concern config-name

Temporary concern until https://github.com/rust-lang/cargo/pull/14615#discussion_r1888730634 gets resolved, because folks may be about to go on holiday soon and I don't want this to get lost. I am not at this time attempting to actually block the FCP if this isn't changed, and I'm happy to defer to consensus; I just want to make sure that this doesn't accidentally FCP without resolving the discussion and reaching some consensus.

[Gordon01]

Happy New Year and Merry Christmas!

I had a lot of work in the last weeks of December and now I'm on New Year vacation. I'll be back in the second half of January, I'll fix the tests, decide on naming.

Wishing everyone a happy new 2025!

[wez]

Just wanted to chime in here to say that WezTerm just now added support for these escapes in main. It should be fine to emit the escapes in earlier versions, but in case you prefer to probe to be sure, you can look for the following environment variables:

TERM_PROGRAM=WezTerm
TERM_PROGRAM_VERSION=20250209-182623-44866cc1

$TERM_PROGRAM_VERSION will be 20250209-182623-44866cc1 or greater in wezterms that support this sequence.

https://github.com/wezterm/wezterm/issues/6581 is the wezterm issue tracking this feature.

[Gordon01]

Hi everyone!

I've changed the feature name to progress report. This name keeps the focus on what the feature does (reporting progress) rather than how it’s rendered.

I've also added WizTerm detection.

@wez also called is like this.

I can't make test to work. It passes locally on Windows and Linux but here on pipeline it behaves differently and I can't figure out why.

[joshtriplett]

@rfcbot resolved config-name

[rfcbot]

:bell: This is now entering its final comment period, as per the review above. :bell:

[epage]

@rfcbot concern config-name

I don't feel the name is resolved yet :)

(and the PR should make sure to update all references to the final name)

[epage]

Hmm, either a delay or it doesn't like me reusing the name

@rfcbot concern config-name-part-2

[kovidgoyal]

Thank you for driving this!

I use Kitty so may gain nothing, but still a great feature!

kitty displays OSC 9 progress percentage in tab titles as of version 0.39, see https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.tab_title_template

[Gordon01]

Thank you for driving this! I use Kitty so may gain nothing, but still a great feature!

kitty displays OSC 9 progress percentage in tab titles as of version 0.39, see https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.tab_title_template

Can you please advice on how is the best to detect kitty?

[kovidgoyal]

Thank you for driving this! I use Kitty so may gain nothing, but still a great feature!

kitty displays OSC 9 progress percentage in tab titles as of version 0.39, see https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.tab_title_template

Can you please advice on how is the best to detect kitty?

Depends on how robust you want to be. The simplest is checking the TERM env var, the most robust is using the XTVERSION escape code combined with a DA1 escape code to avoid timeouts.

[epage]

So TERM=xterm-kitty detects kitty. However, we should use version detection with kitty because of kovidgoyal/kitty#8011

I'm not seeing any way to do version detection for kitty besides XTVERSION and, due to my lack of experience with those call/response escape codes, I'm a bit cautious about what all gotchas there might be.

[epage]

@rfcbot resolved config-name-part-2

[rfcbot]

:bell: This is now entering its final comment period, as per the review above. :bell:

[epage]

With the cargo team having had several months to give input, this has been discussed multiple times in meetings, and all check boxes are marked, I figure we don't need to wait for the full 10 day waiting period. That can help with getting wider input which is more important for more wide impacting changes than things like this which is more niche.

We also don't have to wait until every terminal is supported but future PRs can handle those.

[Gordon01]

Hello, Сargo team! It looks like we're not encountering any issues with this feature. Thank you so much for your support and help - I learned a lot while working on this PR, and I'm really impressed by your passion for high-quality software. No wonder you're the ones making Rust!

@epage on Dec 9, 2024

Ideally I see us breaking this out into a crate as some point

I would also love to break this feature out into a separate crate for reusability in other projects. Can I create a new crate within Cargo’s workspace, following these contribution guidelines?

[epage]

I would also love to break this feature out into a separate crate for reusability in other projects. Can I create a new crate within Cargo’s workspace, following these contribution guidelines?

There is a high bar for crates to be opened by Cargo. I'd be fine having such a crate in the rust-cli org. I've been trying to decide whether it'd be appropriate to have in anstyle repo or not (along with hyperlink helpers)

[Gordon01]

I've been trying to decide whether it'd be appropriate to have in anstyle repo or not (along with hyperlink helpers)

anstyle looks great! The existing anstyle-query crate would be perfect for supports_term_integration() and supports_hyperlinks().

For Progress and Hyperlink and their Display impls:

• The main anstyle crate (which already handles styles)
• A new dedicated crate like anstyle-osc

Would you like me to open an issue in the anstyle repo?