第7章 属性

译文 · 基于 The Rust Reference

原文链接: https://doc.rust-lang.org/reference/attributes.html

r[attributes]

属性

r[attributes.syntax]

InnerAttribute -> `#` `!` `[` Attr `]`

OuterAttribute -> `#` `[` Attr `]`

Attr ->
      SimplePath AttrInput?
    | `unsafe` `(` SimplePath AttrInput? `)`

AttrInput ->
      DelimTokenTree
    | `=` Expression

r[attributes.intro] 属性（attribute）是一种通用的自由形式元数据，其解释取决于名称、约定、语言以及编译器版本。属性的模型来自 ECMA-335 中的 Attributes，语法则来自 ECMA-334（C#）。

r[attributes.inner] 内部属性（inner attributes）作用于声明该属性的那个语法形式本身。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 应用于外层模块或 crate 的一般元数据。
#![crate_type = "lib"]

// 内部属性作用于整个函数。
fn some_unused_variables() {
  #![allow(unused_variables)]

  let x = ();
  let y = ();
  let z = ();
}

r[attributes.outer] 外部属性（outer attributes）作用于紧跟在该属性之后的语法形式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 标记为单元测试的函数
#[test]
fn test_foo() {
    /* ... */
}

// 条件编译的模块
#[cfg(target_os = "linux")]
mod bar {
    /* ... */
}

// 用于抑制警告/错误的 lint 属性
#[allow(non_camel_case_types)]
type int8_t = i8;

r[attributes.input] 属性由指向该属性的路径组成，其后可跟一个可选的定界记号树，其解释由该属性定义。除宏属性外，属性还允许输入为等号（=）后跟一个表达式。更多细节见下文的元项语法。

r[attributes.safety] 某些属性的应用可能是不安全的。为避免使用这些属性时出现未定义行为，必须满足某些编译器无法检查的义务。为断言这些义务已满足，需将属性包在 unsafe(..) 中，例如 #[unsafe(no_mangle)]。

下列属性是不安全的：

• export_name
• link_section
• naked
• no_mangle

r[attributes.kind] 属性可分为以下种类：

• 内置属性
• 过程宏属性
• Derive 宏辅助属性
• 工具属性

r[attributes.allowed-position] 属性可应用于语言中的多种形式：

• 所有项声明接受外部属性，而外部块、函数、实现和模块接受内部属性。
• 大多数语句接受外部属性（表达式语句的限制见表达式属性）。
• 块表达式接受外部与内部属性，但仅当它们是表达式语句的外层表达式，或是另一个块表达式的最终表达式时。
• 枚举变体以及结构体和联合体的字段接受外部属性。
• match 表达式的分支接受外部属性。
• 泛型生命周期或类型参数接受外部属性。
• 表达式仅在有限情况下接受外部属性，细节见表达式属性。
• 函数、闭包以及函数指针的参数接受外部属性。这包括函数指针与外部块中以 ... 表示的可变参数上的属性。
• 内联汇编的模板字符串与操作数接受外部属性。语义上仅接受某些属性；细节见 [asm.attributes.supported-attributes]。

r[attributes.meta]

元项属性语法

r[attributes.meta.intro] “元项”（meta item）是大多数内置属性用于 [Attr] 规则的语法。其文法如下：

r[attributes.meta.syntax]

@root MetaItem ->
      SimplePath
    | SimplePath `=` Expression
    | SimplePath `(` MetaSeq? `)`

MetaSeq ->
    MetaItemInner ( `,` MetaItemInner )* `,`?

MetaItemInner ->
      MetaItem
    | Expression

r[attributes.meta.literal-expr] 元项中的表达式必须宏展开为字面量表达式，且不得包含整数或浮点类型后缀。非字面量表达式在语法上会被接受（并可传给过程宏），但在解析之后会被拒绝。

r[attributes.meta.order] 注意：若属性出现在另一个宏之内，它会在该外层宏之后展开。例如，下列代码会先展开 Serialize 过程宏，该宏必须保留 include_str! 调用以便其随后被展开：

1
2
3
4
5

#[derive(Serialize)]
struct Foo {
    #[doc = include_str!("x.md")]
    x: u32
}

r[attributes.meta.order-macro] 此外，属性中的宏仅在应用于该项的所有其他属性之后才展开：

1
2
3
4
5

#[macro_attr1] // 最先展开
#[doc = mac!()] // `mac!` 第四个展开。
#[macro_attr2] // 第二个展开
#[derive(MacroDerive1, MacroDerive2)] // 第三个展开
fn foo() {}

r[attributes.meta.builtin] 各种内置属性使用元项语法的不同子集来指定其输入。下列文法规则展示了一些常用形式：

r[attributes.meta.builtin.syntax]

@root MetaWord ->
    IDENTIFIER

MetaNameValueStr ->
    IDENTIFIER `=` (STRING_LITERAL | RAW_STRING_LITERAL)

@root MetaListPaths ->
    IDENTIFIER `(` ( SimplePath (`,` SimplePath)* `,`? )? `)`

@root MetaListIdents ->
    IDENTIFIER `(` ( IDENTIFIER (`,` IDENTIFIER)* `,`? )? `)`

@root MetaListNameValueStr ->
    IDENTIFIER `(` ( MetaNameValueStr (`,` MetaNameValueStr)* `,`? )? `)`

元项的一些示例如下：

r[attributes.activity]

活跃属性与惰性属性

r[attributes.activity.intro] 属性要么是活跃的（active），要么是惰性的（inert）。在属性处理过程中，活跃属性会从其所附着的形式上移除自身，而惰性属性则保留在原处。

cfg 与 cfg_attr 属性是活跃的。属性宏是活跃的。所有其他属性都是惰性的。

r[attributes.tool]

工具属性

r[attributes.tool.intro] 编译器可以允许供外部工具使用的属性，每个工具位于工具 prelude 中各自的模块内。属性路径的第一段是工具名称，其后可有一段或多段，其解释由该工具决定。

r[attributes.tool.ignored] 当某工具未在使用时，该工具的属性会被无警告地接受。当工具在使用时，由该工具负责处理与解释其属性。

r[attributes.tool.prelude] 若使用了 no_implicit_prelude 属性，则工具属性不可用。

1
2
3
4
5
6
7
8

// 告知 rustfmt 工具不要格式化其后的元素。
#[rustfmt::skip]
struct S {
}

// 控制 clippy 工具的“圈复杂度”阈值。
#[clippy::cyclomatic_complexity = "100"]
pub fn f() {}

注意 rustc 当前识别的工具有 “clippy”、“rustfmt”、“diagnostic”、“miri” 和 “rust_analyzer”。

r[attributes.builtin]

内置属性索引

以下是所有内置属性的索引。

• 条件编译

  • cfg —— 控制条件编译。
  • cfg_attr —— 有条件地包含属性。

• 测试

  • test —— 将函数标记为测试。
  • ignore —— 禁用测试函数。
  • should_panic —— 表示测试应产生 panic。

• Derive

  • derive —— 自动 trait 实现。
  • automatically_derived —— 由 derive 创建的实现的标记。

• 宏

  • macro_export —— 导出 macro_rules 宏以供跨 crate 使用。
  • macro_use —— 扩展宏可见性，或从其他 crate 导入宏。
  • proc_macro —— 定义类函数宏。
  • proc_macro_derive —— 定义 derive 宏。
  • proc_macro_attribute —— 定义属性宏。

• 诊断

  • allow、expect、warn、deny、forbid —— 改变默认 lint 级别。
  • deprecated —— 生成弃用通知。
  • must_use —— 对未使用的值生成 lint。
  • diagnostic::on_unimplemented —— 提示编译器在 trait 未实现时发出特定错误消息。
  • diagnostic::do_not_recommend —— 提示编译器不要在错误消息中显示某个 trait 实现。

• ABI、链接、符号与 FFI

  • link —— 指定与 extern 块链接的本地库。
  • link_name —— 指定 extern 块中函数或静态项的符号名。
  • link_ordinal —— 指定 extern 块中函数或静态项的符号序号。
  • no_link —— 阻止链接某个 extern crate。
  • repr —— 控制类型布局。
  • crate_type —— 指定 crate 类型（库、可执行文件等）。
  • no_main —— 禁用发出 main 符号。
  • export_name —— 指定函数或静态项的导出符号名。
  • link_section —— 指定函数或静态项所用的目标文件节区。
  • no_mangle —— 禁用符号名改写。
  • used —— 强制编译器在输出目标文件中保留某个静态项。
  • crate_name —— 指定 crate 名称。

• 代码生成

  • inline —— 提示内联代码。
  • cold —— 提示某函数不太可能被调用。
  • naked —— 阻止编译器发出函数序言与尾声。
  • no_builtins —— 禁用某些内置函数的使用。
  • target_feature —— 配置特定平台的代码生成。
  • track_caller —— 将父调用位置传给 std::panic::Location::caller()。
  • instruction_set —— 指定生成函数代码所用的指令集。

• 文档

  • doc —— 指定文档。更多信息见 The Rustdoc Book。文档注释会被转换为 doc 属性。

• Prelude

  • no_std —— 从 prelude 中移除 std。
  • no_implicit_prelude —— 禁用模块内的 prelude 查找。

• 模块

  • path —— 指定模块的文件名。

• 限制

  • recursion_limit —— 设置某些编译期操作的最大递归限制。
  • type_length_limit —— 设置多态类型的最大大小。

• 运行时

  • panic_handler —— 设置处理 panic 的函数。
  • global_allocator —— 设置全局内存分配器。
  • windows_subsystem —— 指定要链接的 Windows 子系统。

• 特性

  • feature —— 用于启用不稳定或实验性的编译器特性。rustc 中已实现的特性见 The Unstable Book。

• 类型系统

  • non_exhaustive —— 表示将来会向类型添加更多字段/变体。

• 调试器

  • debugger_visualizer —— 嵌入指定类型调试器输出的文件。
  • collapse_debuginfo —— 控制宏调用在调试信息中的编码方式。