Tracking Issue for `-Z terminal-width`

[ehuss]

Status: The rustc side has been stabilized in 1.64 as the --diagnostic-width option. This tracking issue is still open for the cargo side of changes. See #84673 (comment).

This is a tracking issue for the -Z terminal-width flag. This flag tells rustc the width of the terminal so that it can truncate long lines in diagnostic output to the correct length. A corresponding flag of the same name is available in Cargo, which detects the terminal width and sends in the appropriate value to rustc.

Unresolved Questions

Unknown.

Implementation history

• Original issue: rustc should "ellipsis" very long lines when printing warnings #62999
• Original implementation: Strip code to the left and right in diagnostics for long lines #63402
• Cargo implementation: Add support for rustc's -Z terminal-width. cargo#8427
• Stabilization and option change: sess: stabilize -Zterminal-width as --diagnostic-width #95635

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also used as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

[ehuss]

cc @rust-lang/wg-diagnostics Hope you don't mind I open this. If anyone knows of any unresolved questions or blockers for this, I would appreciate if you could update the issue (or perhaps there is no desire to carry this forward?).

[shepmaster]

I wanted this feature to be able to automatically format errors to a width suitable for inclusion on slides. However, it does not:

% rustc +nightly src/main.rs -Z terminal-width=80
error[E0425]: cannot find value `and_then_an_argument` in this scope
 --> src/main.rs:2:43
  |
2 |     a_very_long_function_name_that_pushes(and_then_an_argument);
  |                                           ^^^^^^^^^^^^^^^^^^^^ not found in this scope

this scope exceeds the specified width of 80 columns. I'd prefer it be

% rustc +nightly src/main.rs -Z terminal-width=80
error[E0425]: cannot find value `and_then_an_argument` in this scope
 --> src/main.rs:2:43
  |
2 |     a_very_long_function_name_that_pushes(and_then_an_argument);
  |                                           ^^^^^^^^^^^^^^^^^^^^ not found in
  |                                                                this scope

Should I register this as a separate issue?

[estebank]

That should indeed be a separate issue, I think. It is related, but independent. I also know it will be very difficult to come up with a good layout algorithm :-/

For things like slides, I think a better option would be html output.

[davidtwco]

I think that we should go ahead with stabilizing this, it's a small compiler feature that hasn't seen any major changes since it was implemented, and is useful for people invoking rustc through build systems other than Cargo.

Stabilization PR: #95635

@rfcbot fcp merge

Brief summary

rustc currently detects the width of the terminal and will truncate diagnostic output when it includes source code lines which are longer than the terminal width.

error[E0308]: mismatched types
  --> $DIR/flag-human.rs:7:17
   |
LL | ..._: () = 42;
   |       --   ^^ expected `()`, found integer
   |       |
   |       expected due to this

error: aborting due to previous error

For more information about this error, try `rustc --explain E0308`.

However, rustc is unable to detect the terminal width when it is being invoked indirectly (i.e. through a build tool like Cargo). --terminal-width (currently -Zterminal-width) enables build tools to provide the terminal width to rustc so that it can continue to perform this truncation.

Implementation History

• Original issue: rustc should "ellipsis" very long lines when printing warnings #62999
• Strip code to the left and right in diagnostics for long lines #63402 (@estebank, Aug 2019) implemented diagnostic truncation and introduced -Zterminal-width
• errors: use -Z terminal-width in JSON emitter #73763 (@davidtwco, Jun 2020) updated the JSON emitter to use -Zterminal-width in the rendered field
• Add support for rustc's -Z terminal-width. cargo#8427 (@davidtwco, Jun 2020) added support to Cargo for providing this flag.

Test Coverage

• src/test/ui/terminal-width (9 tests)

FAQ

1. Is a flag necessary to turn this behaviour off?
--terminal-width doesn't do anything if it hasn't been explicitly provided to the compiler. When emitting an error and deciding whether to truncate output, rustc uses (in priority order):

1. --terminal-width (if provided)
2. If the compiler is being invoked for UI testing, then the terminal width is fixed at 140 columns.
3. Using term_size to determine the current terminal width, and if that fails, defaulting to 140 columns.

Having this flag on stable won't change any behaviour, just allow tools to tell rustc the terminal width.

2. Can the terminal width be determined through environment variables?
Shells don't provide the terminal size to processes as an environment variable. There are "fake" environment variables available in the shell - namely COLUMNS and LINES - from some shells, but the shell wouldn't be able to keep these variables up to date if they were provided to a process, so it doesn't give them to the process at all. Processes can determine the terminal width by sending ioctl commands, asking stty size, or by listening for SIGWINCH signals. rustc uses the term_size crate to determine the terminal width when possible.

Outstanding bugs

• -Z terminal-width should account for compiler-generated text, not just user-supplied text #95432
  • This isn't a major blocker and could be addressed after stabilization (it relates more to diagnostic truncation in general rather than the specific flag for build tools to indicate the terminal width, which is what this stabilization concerns).

Notes

• If this is stabilized, then Cargo will need to be updated to use the stable flag, cc @ehuss

[rfcbot]

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

• @Aaron1011
• @cjgillot
• @davidtwco
• @eddyb
• @estebank
• @lcnr
• @matthewjasper
• @michaelwoerister
• @nagisa
• @nikomatsakis
• @oli-obk
• @petrochenkov
• @pnkfelix
• @wesleywiser

No concerns currently listed.

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.

[nikomatsakis]

@rfcbot reviewed