Document warning suppression heuristic

[felixwrt]

Problem

Cargo suppresses warnings from depdendencies that are pulled in via git or crates.io. For path dependencies, warnings are shown.

I discovered this when I was patching a depdendency locally in a project that is compiled with -D warnings. There, the exact same crate that worked fine when pulled in via crates.io / git failed to compile when using a path dependency. That was pretty surprising and took me a while to figure out.

I searched online but couldn't find any official documentation of this behavior. I think the heuristic makes sense, but it should be mentioned in the official docs.

Steps

I've created a small repo that demonstrates the different behavior for git and path dependencies: https:/felixwrt/cargo_warning_heuristic

Possible Solution(s)

Add some docs to the cargo book that explain this behavior.

Notes

I really hope I didn't miss that it's already in the docs. If that's the case: sry for the noise!

Version

cargo 1.79.0 (ffa9cf99a 2024-06-03)
release: 1.79.0
commit-hash: ffa9cf99a594e59032757403d4c780b46dc2c43a
commit-date: 2024-06-03
host: x86_64-unknown-linux-gnu
libgit2: 1.7.2 (sys:0.18.3 vendored)
libcurl: 8.6.0-DEV (sys:0.4.72+curl-8.6.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 2023
os: Ubuntu 22.4.0 (jammy) [64-bit]

[epage]

We make passing references to cap lints at

• https://doc.rust-lang.org/cargo/reference/semver.html?highlight=cap%20lint#new-lints
• https://doc.rust-lang.org/cargo/reference/manifest.html?highlight=cap%20lint#the-lints-section

iiuc we don't apply cap lints to local dependencies, assuming they are all in your repo and under your control. What is right for path patches is best described as "it depends".

A question I have is where we could note this that people who need it can find it. In this case, the use case is confusion over patching. I'm unsure what other points of confusion there might be.

We don't have a general "compilation" section in the docs. We could note this in one or several of

• FAQ
• Path dependencies
• Overriding dependencies

[felixwrt]

IMO there's no place in the docs currently where the info would fit nicely. Probably FAQ but then it's probably difficult to find.

There's also #8546 which proposes an option to specify whether warnings from dependencies should be shown or not. To me (and the ones who commented on that issue), this sounds like a good addition. Additionally, if there was an optional key like propagate_warnings that controls whether lints from a dependency are shown, this could naturally be documented in "Specifying Dependencies" and the docs could mention the default behavior (git/crates.io: yes, path: no).

Another idea would be to add a hint to the output of cargo when warnings from path dependencies are shown. Something like:

    = note: warning originating in path dependencies are shown by default, see LINK_TO_DOCS

[epage]

Another idea would be to add a hint to the output of cargo when warnings from path dependencies are shown. Something like:

If we showed a note like that, we'd need to limit it to non-workspace member path dependencies. Even then, it could end up being annoying for people not in the patch situation.