Rust Tooling and Code Quality

Compiler Diagnostics

Compiler diagnostics in rustc are structured error, warning, and help messages designed to explain what went wrong, why the rule exists, and how to fix the problem. Every major compile error carries a numbered error code (such as E0382 or E0502) backed by a built-in textbook explanation accessible offline via rustc --explain <CODE>.

Anatomy of a `rustc` Diagnostic Message:

error[E0382]: borrow of moved value: `payload`     <-- 1. Error Code & Summary
 --> src/main.rs:5:20                              <-- 2. File:Line:Column Span
  |
3 |     let payload = String::from("data");        <-- 3. Context Note (`move occurs...`)
  |         ------- move occurs because `payload` has type `String`,
  |                 which does not implement the `Copy` trait
4 |     let consumed = payload;                    <-- 4. Secondary Span (`value moved here`)
  |                    ------- value moved here
5 |     println!("{payload}");                     <-- 5. Primary Error Span (`^^^`)
  |               ^^^^^^^^^ value borrowed here after move
  |
help: consider cloning the value if the performance cost is acceptable <-- 6. Fix Suggestion
  |
4 |     let consumed = payload.clone();
  |                           ++++++++

Reading Extended Error Explanations (rustc --explain)

Whenever rustc emits an error code like error[E0382], you can read a detailed explanation with self-contained examples right in your terminal:

rustc --explain E0382

Controlling Diagnostic Output Formats (--error-format)

Build tools, CI pipelines, and editor plugins customize how rustc and cargo render diagnostics:

Command / Flag Output Format Primary Use Case
cargo check (Default) Multi-line human-readable spans with ANSI colors Terminal development
cargo check --message-format=short Single-line file:line:col: error: msg per diagnostic Quick grep / compact terminal logs
cargo check --message-format=json Machine-readable JSON objects with exact byte offsets and suggested replacements IDEs (rust-analyzer), cargo fix, and CI annotation bots
CARGO_TERM_COLOR=always Forces ANSI color codes even when piped into a pager or CI log GitHub Actions / GitLab CI logs

Customizing Diagnostic Messages on Your Own Traits (#[diagnostic::on_unimplemented])

Stabilized in Rust 1.78, the #[diagnostic::on_unimplemented] attribute allows library authors to customize the exact compiler error message, label, and note displayed to users when a type fails to implement your trait!

// ❌ does not compile
#[diagnostic::on_unimplemented(
    message = "`{Self}` cannot be serialized as a wire frame",
    label = "`{Self}` does not implement `WireEncode`",
    note = "Implement `WireEncode` manually or wrap the value in `RawBytes`"
)]
pub trait WireEncode {
    fn encode(&self) -> Vec<u8>;
}

struct UnregisteredPacket {
    id: u32,
}

fn send_frame<T: WireEncode>(item: &T) -> Vec<u8> {
    item.encode()
}

fn main() {
    let pkt = UnregisteredPacket { id: 1 };
    let _ = send_frame(&pkt);
}

error[E0277]: `UnregisteredPacket` cannot be serialized as a wire frame
  --> src/main.rs:21:24
   |
21 |     let _ = send_frame(&pkt);
   |             ---------- ^^^^ `UnregisteredPacket` does not implement `WireEncode`
   |             |
   |             required by a bound introduced by this call
   |
   = help: the trait `WireEncode` is not implemented for `UnregisteredPacket`
   = note: Implement `WireEncode` manually or wrap the value in `RawBytes`
note: required by a bound in `send_frame`
  --> src/main.rs:15:18
   |
15 | fn send_frame<T: WireEncode>(item: &T) -> Vec<u8> {
   |                  ^^^^^^^^^^ required by this bound in `send_frame`