diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 7bfd3a13..895f9f0d 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -3,6 +3,7 @@ [Introduction](./README.md) - [Usage](./usage.md) - [Installation](./usage/installation.md) + - [Setting Lint Levels](./usage/setting-lint-levels.md) - [Lint Crate Declaration](./usage/lint-crate-declaration.md) - [Lint Crate Security](./usage/lint-crate-security.md) - [Lint Development](./lint-dev.md) diff --git a/docs/book/src/usage/setting-lint-levels.md b/docs/book/src/usage/setting-lint-levels.md new file mode 100644 index 00000000..3cea3d90 --- /dev/null +++ b/docs/book/src/usage/setting-lint-levels.md @@ -0,0 +1,53 @@ +# Setting Lint Levels +Once your crate is configured to run some lints, it quickly becomes important to control the lint levels within your +code. Marker provides the ability to use normal lint control attributes like `#[allow(...)]` `#[deny(...)]` and others +to control the behavior of marker lints. + +## On nightly +Marker uses the `marker::` tool prefix for lints. In order for rustc to recognize this prefix, it requires marker to be +registered via the [`#[register_tool()]` feature](https://github.com/rust-lang/rust/issues/66079). + +If your crate is compiled using nightly, then controlling lints is as simple as placing `#![feature(register_tool)]` +and `#![register_tool(marker)]` at the top of your crate `lib.rs` or `mod.rs` file. You can then use all of the normal +lint attributes you might usually use, on marker provided lints, like `#[allow(marker::my_lint)]`. + +```rust +// These attributes need to be at the crate root +#![feature(register_tool)] +#![register_tool(marker)] + +... + +// Marker lints can be controlled like this +#[allow(marker::my_lint)] +fn foo() {} +``` + +## On Stable +If your project isn't on nightly, you can still use the `register_tool` attribute, you'll just need to add some extra +guards around it. Marker provides config arguments to rust during the lint passes, so that your linted code can +conditionally apply attributes only during the marker run. + +Specifically marker passes `--cfg=marker` and a `--cfg=marker="my_crate"` flag for each lint crate. This means that you +can use `#[cfg_attr(marker, foo)]` to conditionally apply the `foo` attribute only during lint runs. + +This conditional compilation can be used to leverage the fact that lints run using nightly, without requiring the +linted crate to compile using nightly. To do this, add `#![cfg_attr(marker, feature(register_tool))]` and +`#![cfg_attr(marker, register_tool(marker))]` attributes to the top of your crate file, to register marker as a tool. +Then you can apply lint level attributes like `#[cfg_attr(marker, allow(marker::foo))]` to control your marker lints. + +Additionally, if there are attributes you only want active when marker is aware of +certain lint crates, you can conditionally apply your attribute with something like +`#[cfg_attr(marker = "my_crate", allow(marker::foo))]`. + +```rust +// These attributes need to be at the crate root +#![cfg_attr(marker, feature(register_tool))] +#![cfg_attr(marker, register_tool(marker))] + +... + +// Marker lints can be controlled like this +#[cfg_attr(marker, allow(marker::my_lint))] +fn foo() {} +```