Skip to content

Latest commit

 

History

History
182 lines (141 loc) · 9.67 KB

README_crates_io.md

File metadata and controls

182 lines (141 loc) · 9.67 KB
Raw

Purpose

Aliases for #[allow(...)] local lint permissions/suppressions. You can have multiple aliases, each with its name - semantic.

Alternatives

  • Use allow crate for "scoped" aliases, grouped in modules, reflecting the lint paths in Rust. Macros for standard lints are at the crate's root and also re-exported under a module (rustc::), and macros for other lints are under their own modules (clippy:: and rustdoc::).
  • Use allow_prefixed for "prefixed", where standard lints are at the crate's root, and other lints are also under the crate's root, but prefixed with rustdoc__ and clippy__.

The problem

Let's say you #[allow(...)] the same lint (either rustc standard (prefixless) lint, or lints prefixed with clippy:: or rustdoc::), and you do so at many places in your code. Even though it's the same lint, you may have different reasons for allowing it. However, #[allow(...)] doesn't carry your intention.

Unfortunately, we can't alias lints with use either. (Why? Because lint names are not (proc) macros, but special compiler symbols.) Of course, you could add a comment, but that's haphazard.

This crate defines one attribute macro per each lint (other than crate-level only lints, more below). Those macros don't take any attribute parameters. They inject #[allow(lint-name-here)] in front of your code.

You can import same macros as many times under as many names you need. For example:

  • use allow::anonymous_parameters as allow_anonymous_params_legacy;
  • use allow::rustdoc_missing_doc_code_examples as allow_rustdoc_examples_linked;
  • use allow::rustdoc_missing_doc_code_examples as allow_rustdoc_examples_none_trivial;
  • use allow::clippy_await_holding_lock as allow_clippy_await_holding_lock;

Then apply #[allow_anonymous_params_legacy], #[allow_rustdoc_examples_linked], #[allow_rustdoc_examples_none_trivial], #allow_clippy_await_holding_lock (or as you name them) before your struct/enum/function/variable..., indicating your intention.

Side benefit: Rust would validate the (aliased) names, hence no typos. So you can grep or search for them at anytime. Your team could have a prelude-like module, or crate, re-exporting the aliases.

Scope

In scope

  • Rust versions 1.45, 1.49.0, 1.52.1, 1.58.1, 1.61.0, 1.69.0, 1.70.0-beta.1, 1.71.0-nightly and maybe some, but seemingly not all, versions in between. See "Out of scope" below.
  • stable and nightly (but we may need your help with maintenance).
  • rustc lints ("standard" with no prefix); clippy:: & rustdoc:: lints. But mostly lints that are current.
  • Clippy: allow version 0.1.0 has all Clippy lints supported by Rust 1.45`. The author is adding newer lints (and specifying version ranges for lints that have been deprecated/removed later).

Limited scope

  • Negative build tests for Rust below 1.63 (down to 1.45). If we do use ui_test crate for testing, we can fully test only from Rust 1.63. Alternatively, could you help implement the negative build tests with trybuild crate?

    Lints (macros) do get validated for those lower Rust versions, too. And the tests that require Rust 1.63+ cover functionality that is used for lower Rust versions, too. Meaning: This is well tested.

  • The autogenerated Rustdoc for lint macros can't mention the original lint being aliased in Rust below 1.54. The best we can do is: "Alias to #[allow(...)] a lint with a similar name as imported from allow or allow_prefixed."

  • Support for all possible Rust versions since 1.45. Adding lints (macros), marking them as obsolete and removing them based on Rust version is not automated. Mistakes happen. Help report them and fix them.

    The good news: Thanks to our test suite, fixes for any mistakes mean only extending the range of compatible Rust versions (for any lint in question), but never restricting the range. Hence, any fixes are backward compatible.

Out of scope

  • some Rust versions, like 1.63, 1.65.0, 1.66.1, 1.67.0, 1.67.1, 1.68.0, 1.68.2 (at least so for the mainstream x64 Linux target: x86_64-unknown-linux-gnu). Why? Because they don't support some rustc (standard, prefixless) lints, even though those lints exist in both some earlier and later versions. However, some major versions in-between may work. And some older versions, are supported. See above.

  • Lint groups (like #[allow(unused)]). Indeed, they do have their place (for example: fast prototyping). But they are contrary to the purpose of this crate: To differentiate between the use cases of ignoring the same lint.

  • Crate level-only ("inner") attributes. They don't work with #[allow(...)], but only with #![allow(...)] and only at crate level. That means (in general) much fewer repetitions than #[allow(...)] sprinkled around the code (granular).of these - and even if you do,

    ---- <- TODO

    You can give thumbs up to rust-lang/rust #54726. Suppose it is implemented. However, top level attributes would most likely have to come before any use aliases, so we wouldn't be able to alias macros generating #![allow(...)] anyway, unfortunately - no semantic benefit. (We could alias them in other modules or crates, and call them without any use imports - with a fully qualified path, like #![our_allow_crate::lints::non_ascii_idents_legacy] or #![crate::lints::non_ascii_idents_third_party]. To be seen.)

  • Beta version of rustc specifics. Beta version incubation is only for 6 weeks. Or, would you help maintain this?

  • Rust older than 1.45. If there is high demand, we could potentially support down to 1.31 (needed by rustversion crate.) But then we'd have an ugly and more complicated proc macro.

    If you would benefit from allow, it's most likely when the lints you are suppressing are wide spread. Hence, if you choose to refactor so much code, wouldn't you as well like to upgrade it to newer Rust?

  • Custom lints (such as with Dylint). Possible in principle - will you commit to maintain it?

Reporting Issues and Known issues

The tests don't cover rustdoc:: and clippy:: well yet. And clippy:: lints are as of Rust version 1.45 (for now).

See also coop-rs/allow > issues.

Related issues - give thumbs up, please

Efficient proc macros

This does use procedural macros (specifically: attribute macros). Many: One per lint.

Yes, proc macros often slow compilation down. Proc macros usually use syn and quote crates. Those are powerhouses, which parse & quote the code that a macro can inject. However, their power comes with a cost: build time.

But, not so for these macros. allow does not parse the new (generated) code into a TokenStream (before it's injected where you use it). Instead, it composes it (through the proc_macro API).

The tests do have many more dependencies (if we continue to use ui_test - as trybuild may be much faster). So don't judge its speed by cargo test, but by cargo build. (Also, some tests don't run on Windows - see See CONTRIBUTING.md. Of course, the actual crates themselves are platform-independent.)

Crates, crates.io and GIT

This project consists of four crates (and potentially a fifth one may come). Three of them are on crates.io: allow, allow_impl and allow_internal. The fourth one, allow_tests, is not on crates.io, because it is for testing only. (TODO If we continue with ui_test, move its non-ui_test-dependent parts to a fifth crate, so we run them for Rust below 1.63, too.)

They are all under the same GIT repo, which simplifies maintenance.

Contributing

See CONTRIBUTING.md.

Do you know of anyone with

  • experience with https://github.com/dtolnay/trybuild, or with https://github.com/oli-obk/ui_test, or
  • knowledge or involvement in versioning/planning/source code life cycle of rustc (prefixless) lints, (less so rustdoc:: - few), or (very much so) clippy:: lints, or
  • experience with using many lints or using them frequently, and handling their changes coming from rustc/rustdoc/clippy?

License

Allow project is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.