build_runner: add option to clear console when watching

[romeobalta]

As described in #23472.

Running zig build with -fincremental and --watch it's a bit hard to identify what's the up-to-date error state.

This PR allows you to opt-in having the screen cleared on debounce timeout.

[rpkak]

In my opinion, "\x1B[2J\x1B[H" should be moved into std.io.tty.

[ghost]

Also note that std.Progress already has code like this so that could be refactored.

[romeobalta]

I've looked at std.io.tty and it seems to handle only colors not the entire suite of ANSI escape codes. std.Progress on the other hand uses some ANSI codes but it's not the main use of the API and I would rather not import from it.

To me it feels like std.io.tty should hold the ANSI escapes for the screen clearing as well. Does this mean that NO_COLOR/--color off should also disable screen clearing? My assumption is that the main reason you would disable colors is to get rid of the ANSI escapes from the output. Maybe someone from the core team can shed some light.

[alexrp]

Does this mean that NO_COLOR/--color off should also disable screen clearing?

https://no-color.org seems to me to strongly indicate that it's about a preference of colored vs non-colored output, not terminal sequences in general. So I would say no.

[andrewrk]

clearing is pretty aggressive, have you considered simply adding a newline instead?

[mlugg]

clearing is pretty aggressive, have you considered simply adding a newline instead?

FWIW, I absolutely want the "clear" option, and have done for a while. With the reference trace and command also in the output, just blank lines don't separate things enough. I would really like my --watch terminal window to purely be current compile errors.

Ideally we could replace just the previous zig build output, but terminals don't have the necessary capabilities to rewrite scrollback.

[romeobalta]

I agree with @mlugg on this one. I usually just want to expend as little as possible of my attention trying to locate the error in the log and just go back to fixing the code.

I was wondering if it would be better to also allow people to specify their own separator either as a flag or as an option in build.zig. This would enable other edge cases as well. (Eg. I'm running zig build --watch as a job in my editor and surface the errors in a QuickFix list automatically, I can use the separator to clear the QF list between builds).

[weskoerber]

Big thanks to @romeobalta for picking this up!

clearing is pretty aggressive, have you considered simply adding a newline instead?

Why not both? We could have:

• --watch - your standard watch, no terminal manipulation
• --watch=clear - clears terminal before each build
• --watch=newline - adds a newline before each build

IMO, --watch=newline would be a sane default, while --watch=clear would be better suited as an opt-in thing.

[andrewrk]

I'm going to step in and say there must be no additional option. Instead, the defaults must be better.

Newline should be be added unconditionally.

I propose that, when combined with --watch, clearing happens as part of the existing option --prominent-compile-errors which as you can see has been carefully named such that an enhancement such as making it also clear the terminal makes sense.

[mlugg]

I would be okay with clearing being a part of --prominent-compile-errors. That said, I don't... actually think it makes much sense? The option doesn't really imply that to me. I guess I would argue that it might not be great to clear the terminal unless the user has very clearly asked for it, because they might want their scrollback to stay intact. I as a user would probably be pretty annoyed about this if I didn't know it thanks to keeping up with this PR, since I very rarely want my terminal to be cleared, and definitely don't want something doing it without my clear consent (which I would say --watch=clear obviously is, but --prominent-compile-errors isn't really). But, not a hill I'm going to die on; as long as there is a way to do this I'm happy enough.

[ikskuh]

Just wanna tune in and say i'm happy to see it's already being worked on!

It bugs me a lot when working on my OS to find out which of the 80some compile errors are part of the "current problem set", so having an auto-clear would be awesome.

my preference is --watch=clear

[cryptocode]

This manner of clearing the screen behaves inconsistently across terminal emulators: In some terminals/configs, the scrollback is preserved. E.g iTerm2/Alacritty seems to do this by default on mac.

This preserve-scrollback behavior is simultaneously useful - because you can look at output history even after clearing - and unhelpful - because it still makes identifying new output hard when there's a lot of output and you need to scroll up.

An alternative

I've been trying some variations locally, and I think that even if clearing is made to work reliably, it's sometimes just too useful to be able to look at the previous output.

I think there's a pretty nice middle ground using a prominent, and searchable, delimiter text (with colors when applicable). Something like this:

diff --git a/lib/compiler/build_runner.zig b/lib/compiler/build_runner.zig
index d73fb6d29d..9f3b60b1f4 100644
--- a/lib/compiler/build_runner.zig
+++ b/lib/compiler/build_runner.zig
@@ -487,6 +487,11 @@ pub fn main() !void {
         var debounce_timeout: Watch.Timeout = .none;
         while (true) switch (try w.wait(gpa, debounce_timeout)) {
             .timeout => {
+                const delimiter_text = "=============== REBUILDING ===============";
+                switch (ttyconf) {
+                    .escape_codes => try std.io.getStdOut().writeAll("\x1b[1;33m\n\n" ++ delimiter_text ++ "\x1b[0m\n\n"),
+                    else => try std.io.getStdOut().writeAll("\n\n" ++ delimiter_text ++ "\n\n"),
+                }
                 debouncing_node.end();
                 markFailedStepsDirty(gpa, run.step_stack.keys());
                 continue :rebuild;

I've been testing this locally and I think this makes it pretty easy to locate where the latest output begins, while keeping the history intact. Not sure if even an opt-in clear flag is necessary, though I suppose some people might still prefer that.

[alexrp]

I think there's a pretty nice middle ground using a prominent, and searchable, delimiter text (with colors when applicable).

I'm not against having something like this as an option, but I don't personally consider it sufficient. I want to be able to run zig build --watch=clear in a pane and have it display nothing but the latest results.

[alexrp]

I as a user would probably be pretty annoyed about this if I didn't know it thanks to keeping up with this PR, since I very rarely want my terminal to be cleared, and definitely don't want something doing it without my clear consent (which I would say --watch=clear obviously is, but --prominent-compile-errors isn't really).

I think this is a pretty strong argument. I can't actually think of any software that has ever cleared my terminal scrollback without my very explicit consent. It would be unfortunate if zig build --watch --prominent-compile-errors did that.

[cryptocode]

I'm not against having something like this as an option, but I don't personally consider it sufficient.
I want to be able to run zig build --watch=clear in a pane and have it display nothing but the latest results.

Yeah I think it's okay to have the clear option, I just think the big delimiter is a good default as it's easy enough to see the latest output (especially compared to status quo), it keeps scrollback, and it works the same on all terminals.