Tracking Issue for [lints] table RFC 3389

[ehuss]

Summary

RFC: #3389
Implementation: #12148, #12168, #12174, #12174
Documentation: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#lints
Issues: A-lints-table Area: [lints] table

This feature adds a [lints] table to Cargo.toml to configure reporting levels for rustc and other tool lints.

See also #3591, #5034

Testing instructions

Requires

• nightly: nightly-2023-05-25 or newer
• beta
• stable

Steps:

1. Switch from attributes to [lints] table per the unstable reference

• -Dwarnings should likely still be passed in explicitly so local experimentation doesn't get blocked on perfection
• CI jobs passing in -Adeprecations likely should still do so since users should see deprecation warnings locally to decide whether to address them

2. Verify lints in CI with a supported compiler by adding the -Zlints flag

Debugging

• Build with --verbose to see what order [lints] and other RUSTFLAGS are being passed to the underlying tool

Example: #12178

Updates Since RFC

• cargo new will automatically inherit the lints table (Automatically inherit workspace lints when running cargo new/init #12174)
• profile.rustflags precedence with [lints] was unspecified. We have put made it a higher precedence.
• rustflags derived from [lints] table are not included in rustc -C metadata hash.
• [lints] should only apply to doctests as much as a diagnostic attributes (#[warn(...)]) in an .rs file applies to doctests
• Per-target or per-target-kind (bin vs lib) [lints] tables is deferred (not in original RFC)
  • Workaround: using diagnostic attributes (e.g. #[warn] in the target)
  • This is helpful when production code (a subset of [lib], [bin]s in a workspace) want to be held to a higher standard than development code (especially tests)
    • e.g. clippy has an unwrap_used lint but people might want that in tests. clippy works around it today by having a allow-unwrap-in-tests setting
  • Since workspaces can have non-production libs and bins, it almost seems like this is more of user-defined lint settings groups and inheriting specific groups. Or put another way, more design work is needed.
• Workspace-wide lints are deferred until they are needed. See Tracking Issue for [lints] table RFC 3389 #12115 (comment) for ideas
  • See also User control over cargo warnings #12235
• We fingerprint all lints; we can optimize the fingerprinting later
  • See also Add a [lints] table to Cargo.toml rfcs#3389 (comment)

Unresolved Issues

• Are we still comfortable with our schema choice? Add a [lints] table to Cargo.toml rfcs#3389 (comment)
• Are we still comfortable with our precedence choice? Add a [lints] table to Cargo.toml rfcs#3389 (comment)

Feedback

Cases that don't work well:

• Some lints are crate specific, like only wanting missing_docs and missing_debug_implementations for [lib]s (comment)
• Some lints are package and maybe crate specific, like disallowed_methods in chore: dogfood Cargo -Zlints table feature #12178
• Explicit inheritance doesn't work well when you want to catch lints for example packages but want the example package to standalone from the workspace (comment)

Future Extensions

No response

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.

[kornelski]

Currently there's no mechanism for controlling Cargo's warnings. Could the [lints] be used to silence Cargo's own warnings too? Like this one?

[epage]

Yes, one of the future possibilities listed in the RFC is for cargo to have configurable lints.

[weihanglo]

This is now stabilized on nightly from nightly-2023-09-10 and later!

[extrawurst]

@weihanglo what is the expected timeline to stabilize it?

[jhpratt]

what is the expected timeline to stabilize it?

It is stable on nightly. It will reach the stable compiler in 1.75.

[mcandre]

Dumb question, is the lints section in a Rust crate inherited by downstream projects?

I love linting, but I am wary of accidentally forcing a particular lint configuration onto my users.

[weihanglo]

If my memory hasn't rusty, then yes. Dependencies will compile with their lint configurations. However, users are not expected to see any compilation failure since Cargo uses --cap-lints to stop dependency warnings from propogating to users. See relevant code below:

cargo/src/cargo/core/compiler/mod.rs

Lines 883 to 894 in d2f6a04

	fn add_cap_lints(bcx: &BuildContext<'_, '_>, unit: &Unit, cmd: &mut ProcessBuilder) {
	// If this is an upstream dep we don't want warnings from, turn off all
	// lints.
	if !unit.show_warnings(bcx.config) {
	cmd.arg("--cap-lints").arg("allow");
	// If this is an upstream dep but we *do* want warnings, make sure that they
	// don't fail compilation.
	} else if !unit.is_local() {
	cmd.arg("--cap-lints").arg("warn");
	}
	}

[jwodder]

(I'm not sure if this issue is the best place to ask this; if there's a better location, please let me know.)

Does the syntax for the [lints] tables only allow per-lint settings, or can it also be used to, e.g., deny all warn-by-default lints — perhaps something like lints.clippy.warn = "deny"?

[epage]

warn is a lint group and lint groups are supported. You need to make sure the priority is set correctly so it is correctly applied.

However, I would recommend against it. In general, #![deny(warnings)] (and by extension doing it in the lints table) is generally frowned upon because

• whether you see warnings is dependent on the rust version used so someone using a different Rust version than you might not be able to build your project
• it means your code always has to be "perfect" even when you are experimenting on something

I would instead recommend looking at #8424.

[flip1995]

warn is a lint group and lint groups are supported.

Small correction: warn is not a lint group in Clippy. But all is, which contains all warn-by-default lints. What epage wrote still applies though: #![deny(warnings)] and by extension #![deny(clippy::all)] is an anti-pattern. So to deny warn-by-default Clippy lints, you should use the same alternatives as listed in the linked documentation.

[jwodder]

• whether you see warnings is dependent on the rust version used so someone using a different Rust version than you might not be able to build your project

Just to be clear on this point: Does the [lints] table have an effect when another user builds a crate that uses mine or installs my binary crate? Or does it only take effect when building my crate directly (e.g., in a clone of the source repository)? Does this differ between the rustc lints and the clippy lints?

[MarijnS95]

• cargo new will automatically inherit the lints table

Is there (going to be) a way to force workspace lints on all member crates? Having to add [lints] workspace = true to every Cargo.toml in my workspace is not only verbose, it also turns this into an opt-in (that we'd have to watch out for very carefully in PRs that add new crates) rather than being a set of rules that are unconditionally enforced on all crates in our repo / workspace.

[epage]

#12976 was just merged which added the following to the documentation

Generally, these will only affect local development of the current package.
Cargo only applies these to the current package and not to dependencies.
As for dependents, Cargo suppresses lints from non-path dependencies with features like
--cap-lints.

[epage]

• cargo new will automatically inherit the lints table

Is there (going to be) a way to force workspace lints on all member crates? Having to add [lints] workspace = true to every Cargo.toml in my workspace is not only verbose, it also turns this into an opt-in (that we'd have to watch out for very carefully in PRs that add new crates) rather than being a set of rules that are unconditionally enforced on all crates in our repo / workspace.

#12208 is our general issue for considering implicit inheritance. If we should consider piece-meal implicit inheritance, I think that should also be discussed there.