Guidelines for referring to tools and compilers

[ehuss]

I think the authoring guide should have some guidelines for when, why, and how to refer to tools and implementations. In particular, things like rustc, clippy, cargo, rustfmt, miri, etc. The Reference occasionally refers to these things when it seems like that information would provide very helpful context, but there's a certain balance of doing that too little or too much. What are the guidelines for that balance?

There is a slightly different issue in #2040 for implementation-specific guidelines.

Some examples from the Reference:

• rustc currently only allows the clippy and rustfmt tool attributes. It has not yet been decided if the tool attribute space should be extensible (and if so, how).
• The feature attribute links to the Unstable book.
• The description of user extensible cfg values mentions the way to do that is via rustc --cfg.
• The test cfg is set via rustc --test.
• Identifiers that start with an underscore are a convention to silence an unused warning in rustc.
• The dynamic and static C-runtime mentions rustc -C target-feature=+crt-static
• A note about the hazards of using #[inline] and the relationship to how rustc works.
• How target-features and target-cpu's are related via rustc options.
• Note about how you can find the available lints in the lint attribute docs.
• Note about what #[deprecated] does in rustc.
• Defaults for recursion_limit and type_length_limit.
• Mentions of certain hazards, like overflowing literals will generate a warning by rustc.
• Lots of documentation related to #[link] needs to cross-link with the rustc docs.
• The behavior of unwinding across nounwind abi uses an illegal instruction in rustc.
• An explanation of the requirement to use extern alloc; due to the way things work.
• How to write a proc-macro with Cargo.
• Note about security concerns of proc-macros.
• Source files discuss filesystems specifically, but in theory there could be other ways that source is loaded. How rustc-specific is that?