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.

[alexrp]

I would personally prefer something like --watch-clear. The with doesn't really add any clarity, but watch clarifies that it affects --watch.

It also needs to be added to the help text in usage().

[mlugg]

I would suggest that --watch=clear might be even better?

[alexrp]

That works for me too. Though I don't know if we expect to add other options that affect --watch in the future?

[mlugg]

I think let's YAGNI this for the minute: --watch=clear feels to me like the simplest approach for now.

[romeobalta]

Seen this after pushing update to --watch-clear, will update to --watch=clear.

[rpkak]

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

[wooster0]

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

[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.