Add simple markdown formatting to `rustc --explain` output #112697

tgross35 · 2023-06-16T06:31:30Z

This is a second attempt at #104540, which is #63128 without dependencies.

This PR adds basic markdown formatting to rustc --explain output when available. Currently, the output just displays raw markdown: this works of course, but it really doesn't look very elegant. (output is rustc --explain E0038)

After this patch, sample output from the same file:

This also obeys the --color always/auto/never command option. Behavior:

If pager is available and supports color, print with formatting to the pager
If pager is not available or if printing with formatting to stdout fails, fallback to printing without formatting
Follow --color always/never if supplied
If everything fails, just print plain text to stdout

r? @oli-obk
cc @estebank
(since the two of you were involved in the previous discussion)

rustbot · 2023-06-16T06:31:40Z

These commits modify the Cargo.lock file. Unintentional changes to Cargo.lock can be introduced when switching branches and rebasing PRs.

If this was unintentional then you should revert the changes before this PR is merged.
Otherwise, you can ignore this comment.

tgross35 · 2023-06-16T06:35:09Z

I need to tweak the wrapping text printer, it's almost there but sometimes prints slightly too much to the terminal. Do we have a standard algorithm for this anywhere already?

To test with/without the pager, you can override PAGER, PAGER=fake ./build/x86_64-unknown-linux-gnu/stage1/bin/rustc --explain E0038 or $env:PAGER='fake'; .\build\x86_64-pc-windows-msvc\stage1\bin\rustc --explain E0038

bjorn3 · 2023-06-16T09:35:12Z

If formatting is not possible can you keep the current markdown output? I think it is clearer than not having anything to identify code blocks.

tgross35 · 2023-06-16T09:37:02Z

That is what it currently does - if --color never is passed or if there is no TTY and the pager doesn't support it, it just uses the raw text

bjorn3 · 2023-06-16T09:43:39Z

Right, I misread the code.

oli-obk · 2023-06-16T12:35:16Z

compiler/rustc_errors/src/markdown/tests/tests_term.rs

+
+#[test]
+fn test_output() {
+    let bless = std::env::var("MD_BLESS").unwrap_or_default() == "1";


can you connect this to however x test --bless works?

Or make it a ui test that passes --explain and --color=something?

I adjusted bootstrap to set RUST_BOOTSTRAP_BLESS if --bless is passed, so this and other tests can hook into that if needed. I think this should be an alright way to do it, but let me know if you have something better in mind.

bors · 2023-06-28T01:06:31Z

☔ The latest upstream changes (presumably #113105) made this pull request unmergeable. Please resolve the merge conflicts.

oli-obk · 2023-06-30T15:39:01Z

@rustbot author

did anything change that I should review?

tgross35 · 2023-06-30T16:44:12Z

Sorry no not yet, I was trying to figure out the best thing for that test (and got some help on zulip).

tgross35 · 2023-07-02T07:26:00Z

Alright, with that test change I think this should be good again

@rustbot ready

oli-obk · 2023-07-03T15:22:16Z

src/bootstrap/test.rs

@@ -2217,6 +2217,11 @@ fn prepare_cargo_test(
 ) -> Command {
    let mut cargo = cargo.into();

+    // If bless is passed, give downstream crates a way to use it
+    if std::env::args().any(|arg| arg == "--bless") {


There is a bless flag you can check: builder.config.cmd.bless()

This actually came up on Zulip the other day, Clippy and Miri kind of wanted to unite their variables that do the same thing. I did that change in #113298 and requested you for review.

I'll just checkout the relevant parts of that to this one so there's no conflict.

I take this back, there wound up being some more refactoring in that that I don't want to pull into here. So I just made the change you suggested, I can adjust the other PR if this lands first. (should be good to go here again)

Currently, the output of `rustc --explain foo` displays the raw markdown in a pager. This is acceptable, but using actual formatting makes it easier to understand. This patch consists of three major components: 1. A markdown parser. This is an extremely simple non-backtracking recursive implementation that requires normalization of the final token stream 2. A utility to write the token stream to an output buffer 3. Configuration within rustc_driver_impl to invoke this combination for `--explain`. Like the current implementation, it first attempts to print to a pager with a fallback colorized terminal, and standard print as a last resort. If color is disabled, or if the output does not support it, or if printing with color fails, it will write the raw markdown (which matches current behavior). Pagers known to support color are: `less` (with `-r`), `bat` (aka `catbat`), and `delta`. The markdown parser does not support the entire markdown specification, but should support the following with reasonable accuracy: - Headings, including formatting - Comments - Code, inline and fenced block (no indented block) - Strong, emphasis, and strikethrough formatted text - Links, anchor, inline, and reference-style - Horizontal rules - Unordered and ordered list items, including formatting This parser and writer should be reusable by other systems if ever needed.

oli-obk · 2023-07-04T08:41:01Z

@bors r+

bors · 2023-07-04T08:41:03Z

📌 Commit 6a1c10b has been approved by oli-obk

It is now in the queue for this repository.

bors · 2023-07-04T11:43:38Z

⌛ Testing commit 6a1c10b with merge 2e746c34b26ca2c001c862925a4c90ecd672b406...

rust-log-analyzer · 2023-07-04T12:04:23Z

A job failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

bors · 2023-07-04T12:04:51Z

💔 Test failed - checks-actions

tgross35 · 2023-07-04T17:33:04Z

@oli-obk could you retry? It looks like check failed downloading nodejs, server must have been iffy or something

oli-obk · 2023-07-04T18:11:59Z

@bors retry

bors · 2023-07-05T06:18:50Z

⌛ Testing commit 6a1c10b with merge 6dab6dc...

bors · 2023-07-05T08:47:57Z

☀️ Test successful - checks-actions
Approved by: oli-obk
Pushing 6dab6dc to master...

rust-timer · 2023-07-05T10:04:07Z

Finished benchmarking commit (6dab6dc): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-3.2%	[-3.5%, -2.9%]	2
All ❌✅ (primary)	-	-	0

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 654.835s -> 655.25s (0.06%)

rustbot assigned oli-obk Jun 16, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Jun 16, 2023

This comment has been minimized.

Sign in to view

tgross35 force-pushed the explain-markdown branch 2 times, most recently from c85f24a to 0ee3834 Compare June 16, 2023 07:13

oli-obk reviewed Jun 16, 2023

View reviewed changes

tgross35 force-pushed the explain-markdown branch 2 times, most recently from c050bfa to 8e27acb Compare June 30, 2023 06:41

tgross35 mentioned this pull request Jun 30, 2023

RFC: Unblock Cargo feature metadata rust-lang/rfcs#3416

Merged

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 30, 2023

tgross35 force-pushed the explain-markdown branch from 8e27acb to 39a53e0 Compare July 2, 2023 04:44

rustbot added the T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) label Jul 2, 2023

tgross35 force-pushed the explain-markdown branch 2 times, most recently from 29001ab to d8f1c4e Compare July 2, 2023 04:57

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 2, 2023

oli-obk reviewed Jul 3, 2023

View reviewed changes

tgross35 force-pushed the explain-markdown branch from d8f1c4e to 917e5b2 Compare July 3, 2023 19:53

tgross35 force-pushed the explain-markdown branch from 917e5b2 to 6a1c10b Compare July 3, 2023 20:05

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 4, 2023

bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jul 4, 2023

tgross35 mentioned this pull request Jul 4, 2023

Unite bless environment variables under RUSTC_BLESS #113298

Merged

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 4, 2023

bors added the merged-by-bors This PR was explicitly merged by bors. label Jul 5, 2023

bors merged commit 6dab6dc into rust-lang:master Jul 5, 2023

rustbot added this to the 1.72.0 milestone Jul 5, 2023

tgross35 deleted the explain-markdown branch July 5, 2023 16:04

lqd mentioned this pull request May 30, 2024

ICE: !self.intercrate #125767

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add simple markdown formatting to `rustc --explain` output #112697

Add simple markdown formatting to `rustc --explain` output #112697

tgross35 commented Jun 16, 2023 •

edited

Loading

rustbot commented Jun 16, 2023

tgross35 commented Jun 16, 2023

This comment has been minimized.

bjorn3 commented Jun 16, 2023

tgross35 commented Jun 16, 2023

bjorn3 commented Jun 16, 2023

oli-obk Jun 16, 2023

tgross35 Jul 2, 2023

bors commented Jun 28, 2023

oli-obk commented Jun 30, 2023

tgross35 commented Jun 30, 2023

tgross35 commented Jul 2, 2023

oli-obk Jul 3, 2023

tgross35 Jul 3, 2023

tgross35 Jul 3, 2023 •

edited

Loading

oli-obk commented Jul 4, 2023

bors commented Jul 4, 2023

bors commented Jul 4, 2023

rust-log-analyzer commented Jul 4, 2023

bors commented Jul 4, 2023

tgross35 commented Jul 4, 2023

oli-obk commented Jul 4, 2023

bors commented Jul 5, 2023

bors commented Jul 5, 2023

rust-timer commented Jul 5, 2023

Add simple markdown formatting to rustc --explain output #112697

Add simple markdown formatting to rustc --explain output #112697

Conversation

tgross35 commented Jun 16, 2023 • edited Loading

rustbot commented Jun 16, 2023

tgross35 commented Jun 16, 2023

This comment has been minimized.

bjorn3 commented Jun 16, 2023

tgross35 commented Jun 16, 2023

bjorn3 commented Jun 16, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bors commented Jun 28, 2023

oli-obk commented Jun 30, 2023

tgross35 commented Jun 30, 2023

tgross35 commented Jul 2, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tgross35 Jul 3, 2023 • edited Loading

Choose a reason for hiding this comment

oli-obk commented Jul 4, 2023

bors commented Jul 4, 2023

bors commented Jul 4, 2023

rust-log-analyzer commented Jul 4, 2023

bors commented Jul 4, 2023

tgross35 commented Jul 4, 2023

oli-obk commented Jul 4, 2023

bors commented Jul 5, 2023

bors commented Jul 5, 2023

rust-timer commented Jul 5, 2023

Overall result: no relevant changes - no action needed

Add simple markdown formatting to `rustc --explain` output #112697

Add simple markdown formatting to `rustc --explain` output #112697

tgross35 commented Jun 16, 2023 •

edited

Loading

tgross35 Jul 3, 2023 •

edited

Loading