Module diagnostics 

Hard-coded and user-controlled diagnostics

Diagnostics are user messages, like warnings and errors. When they are named for setting a user-overridable level, they are called lints.

When should a diagnostic be a lint

Lints are generally preferred because of the level of control for users.

Use a hard-coded diagnostic when:

• Critical errors
• There is no associated package or workspace. The diagnostic must still be suppressible somehow (e.g. a user explicitly opting in to a config field’s default value)
• The warning message is too important to allow a user to hide (rare)

Adding a diagnostic

The mechanics of adding a diagnostic is dependent on the requirements:

• TOML syntax or manifest schema: passes::emit_parse_diagnostics, rules::PARSE_PASS_RULES
• Lockfile
  • May be overly broad for what dependencies are checked
• Pre-build unit graph
  • Tailored to a specific configuration (features, targets) but requires users to enumerate every configuration
• Post-build unit graph: rules::unused_dependencies::lint_build_results
  • Slow feedback cycle since a build needs to happen
• Does not fit into any idea of a pass: directly call [cargo_util_terminal::Shell::warn] or crate::CargoResult::Err

When evaluating a diagnostic:

• Only evaluate and emit for local packages unless it is for a future-incompat lint

When generating a diagnostic [report][cargo_util_terminal::report::Report]:

• Try to keep the report succinct while ensuring a beginner can understand what is wrong and how to fix. It is a difficult balance to hit; err on the side of providing extra information.
• Messages should generally be a phrase, starting with a lowercase letter. If multiple sentences are needed, consider if a [message][cargo_util_terminal::report::Message] or sub-diagnostic would be more appropriate.
• Only the first lint for a package should emit the lint::Lint::emitted_source

See also rustc’s Errors and Lints

Adding a pass

When a diagnostic requires adding a new pass, keep in mind:

• Cap lints (skip everything for non-local)
• Support for build.warnings
• When errors should block further evaluation within the pass
• Providing a summary at the end, like what is provided by ScopedDiagnosticStats::report_summary
• Prefer data driven passes to simplify adding rules
  • Ensure the pass’ lints are in rules::LINTS, e.g. ensure_parse_passed_in_lints
  • Prefer evaluating the lint level within the pass

See passes::emit_parse_diagnostics as an example.

Re-exports

use cargo_util_schemas::manifest::RustVersion; 🔒

use cargo_util_schemas::manifest::TomlToolLints; 🔒

use crate::CargoResult; 🔒

use crate::util::GlobalContext; 🔒

use crate::workspace::Workspace; 🔒

use crate::workspace::Edition; 🔒

use crate::workspace::Features; 🔒

use crate::workspace::MaybePackage; 🔒

use crate::workspace::Package; 🔒

pub use lint::Lint;

pub use lint::LintGroup;

pub use lint::LintLevel;

pub use lint::LintLevelProduct;

pub use lint::LintLevelSource;

pub use report::AsIndex;

pub use report::TomlSpan;

pub use report::cwd_rel_path;

pub use report::get_key_value;

pub use report::get_key_value_span;

pub use report::workspace_rel_path;

pub use rules::LINT_GROUPS;

pub use rules::LINTS;

Modules

lint 🔒

passes

report 🔒

rules

Structs

GlobalDiagnosticStats

PassOutput

ScopedDiagnosticStats

Enums

ManifestFor

Scope at which a lint runs: package-level or workspace-level.