Crate attr_alias

source ·
Expand description

This crate allows defining arbitrary aliases for attributes.

Aliases are resolved by #[attr_alias]. Since that attribute requires a nightly compliler, #[eval] and eval_block! provide workarounds for use on the stable release channel.

§Alias File

Due to how procedural macros work and to avoid redundancy, this crate will always read aliases from “src/attr-aliases.txt”. Other files may be supported in future versions, but doing so is not currently possible. Open an issue if this is important for your build.

§Syntax

  • Each alias must begin with * and be assigned to a valid attribute value.
  • Aliases can reference others, but referenced aliases must be listed first.

§Example

ⓘ
*default=cfg(*)
*macos=target_os = "macos"
*macos_or_windows=attr_alias(macos, any(*, windows))
// Comments are supported.
*warnings=warn(missing_docs, unused_results)

§Features

These features are optional and can be enabled or disabled in a “Cargo.toml” file.

§Nightly Features

These features are unstable, since they rely on unstable Rust features.

§Dependencies

Although this is a proc_macro crate, it does not depend on proc_macro2, quote, or syn. Therefore, its impact on compile time should be minimal.

§Comparable Crates

The following crates are similar but take different approaches. An overview of benefits and downsides in comparison to this crate is provided for each when expanded.

  • cfg_aliases - Aliases defined using “build.rs” instructions.
    • Pros:
      • Compile time may be reduced. The declarative macro is only used in the build file, but the build file must be compiled as well.
      • Inner attributes are supported without a nightly feature.
    • Cons:
      • Only #[cfg] aliases can be defined.
      • Some configuration options are not supported (e.g., test).
      • Alias names are not checked at compile time.
      • Aliases are not expanded inline, as would be desirable for #[doc(cfg)].

  • macro_rules_attribute - Aliases defined as declarative macros.
    • Pros:
      • Aliases are defined within Rust source files.
      • Aliases can expand to multiple attributes.
      • Declarative macros accepting valid Rust syntax can be used as attributes.
    • Cons:
      • Attributes cannot be attached to statements without a nightly feature.
      • Inner attributes are not supported.
      • Aliases cannot be inserted at a specific part of an attribute (e.g., within not()).
      • Some dependencies are required, which may impact compile time.

Macros§

  • eval_block
    Equivalent to #[eval] but does not have restrictions on where it can be attached.

Attribute Macros§