Attribute 属性

属性是作用在 Rust 语言元素上的元数据。

Rust 中的属性数量非常多。而且具有可扩展性（可自定义属性）。Rust 的属性语法遵从 C# 定义并标准化了的属性规范ECMA-334。

Rust 代码中随处可见属性，有时甚至会多得让人摸不着头脑。本篇是对 Rust 中的属性相关知识的简单总结。水平有限，仅起到抛砖引玉的作用。

概念

整体来讲，属性还是比较好理解的，但是需要先理解一些基本概念：

Inner Attributes（内部属性） 和 Outer Attributes（外部属性）

内部属性（Inner Attribute）是指：一个属性声明在一个元素中，对此元素（比如一般为 crate）整体生效。内部属性用 #![] 声明。

外部属性（Outer Attribute）是指：一个属性声明在一个元素之前，对跟在后面的这个元素生效。外部属性用 #[] 声明。

Rust 中，有些属性可以/只能作内部属性使用，有些属性可以/只能作外部属性使用。

Meta Item Attribute Syntax

Meta Item Attribute Syntax 实际上描述了属性语法的基本结构。

下面表格罗列了所有 Meta Item Attribute Syntax。第一列是语法样式名称，第二列是语法看起来的样子。

Style	Example
MetaWord	no_std
MetaNameValueStr	doc = "example"
MetaListPaths	allow(unused, clippy::inline_always)
MetaListIdents	macro_use(foo, bar)
MetaListNameValueStr	link(name = "CoreFoundation", kind = "framework")

我们在 Rust 代码中看到的所有属性语法都是上述五种中的一种或其组合。

Active 和 insert 属性

一个属性，要么是 active 的，要么是 insert 的。

Active 属性是指，在处理属性（预处理代码）的过程中，active 属性会将它们自己删除，留下所作用的元素。

Insert 属性是指，在处理属性（预处理代码）的过程中，insert 属性会将它们自己保留。

• cfg 和 cfg_attr 属性是 active 的。
• 当编译为 test 模式时，test 属性是 insert 的。编译为非 test 模式时，test 属性是 active 的。
• 属性宏是 active 的。
• 所有其它属性是 insert 的。

属性的分类

Rust 中的属性，可以分为以下四大类。

1. Macro attributes - 宏属性
2. Derive macro helper attributes - 派生宏辅助属性
3. Tool attributes - 工具属性
4. Built-in attributes - 内建属性

Macro Attributes 宏属性

宏属性，也叫属性宏。属于过程宏的一种。

定义过程宏的时候，使用 #[proc_macro_attribute]，加一个固定签名的函数（详见过程宏一章）。

#[proc_macro_attribute]
pub fn return_as_is(_attr: TokenStream, item: TokenStream) -> TokenStream {
	item
}

使用过程宏：

#[return_as_is]
fn invoke() {}

Derive macro helper attributes 派生宏辅助属性

派生宏辅助属性，听起来有点拗口，其实它是这样一个东西：

先定义派生宏

#[proc_macro_derive(HelperAttr, attributes(helper))]
pub fn derive_helper_attr(_item: TokenStream) -> TokenStream {
	TokenStream::new()
}

看如何使用：

#[derive(HelperAttr)]
struct Struct {
	#[helper] field: ()
}

里面那个 #[helper] 就是一个派生宏辅助属性。

Tool Attributes 工具属性

工具属性。Rust 还允许外部工具定义它们自己的属性，并且在独立的命名空间下面。比如：

// Tells the rustfmt tool to not format the following element.
#[rustfmt::skip]
struct S {
}

// Controls the "cyclomatic complexity" threshold for the clippy tool.
#[clippy::cyclomatic_complexity = "100"]
pub fn f() {}

不过如果你想在自己的工具中定义 Tool Attribute，那就想多了。现在 rustc 只认识两个外部工具（及它们内部的属性）：一个是 rustfmt，另一个是 clippy。

Built-in Attributes 内建属性

4 种属性的前面两种：宏属性和派生宏辅助属性，是可以完全自定义的。后面两种：工具属性和内建属性，我们只能用，不能自定义。

Rust 内建了 14 类属性。OMG @_@!!

每一个属性都有自己的用法，有的用法还比较多，可以用到的时候，再去查阅。这里简单罗列说明一下。

• 条件编译
  • cfg
  • cfg_attr
• 测试
  • test
  • ignore
  • should_panic
• 派生
  • derive
• 宏相关
  • macro_export
  • macro_use
  • proc_macro
  • proc_macro_derive
  • proc_macro_attribute
• 诊断
  • allow, warn, deny, forbid - lint 相关标志开关，各种 lint 见附录。
  • deprecated
  • must_use
• ABI, 链接, 符号, 和 FFI
  • link
  • link_name
  • no_link
  • repr
  • crate_type
  • no_main
  • export_name
  • link_section
  • no_mangle
  • used
  • crate_name
• 代码生成
  • inline
  • cold
  • no_builtins
  • target_feature
• 文档
  • doc
• 预引入
  • no_std
  • no_implicit_prelude
• 模块
  • path
• 限制
  • recursion_limit
  • type_length_limit
• 运行时
  • panic_handler
  • global_allocator
  • windows_subsystem
• 语言特性
  • feature - 经常会碰到这里面一些陌生的 feature 名称，需要根据具体的 rustc 版本和所使用的库文档进行查阅。
• 类型系统
  • non_exhaustive

上面的属性中，很多属性，其内容都可以单独开一篇文章来讲解。比如，条件编译相关的属性，FFI 相关属性等。

参考

本文内容主要来自：https://doc.rust-lang.org/reference/attributes.html。 加入了作者的一些理解。各位同学有时间的话，最好将上述文档中的内容每一个都仔细过一遍。这样，需要用到的时候，温习一下就会用了。也并不是太难的事儿。

Unstable Book 对 rustc 的 flags 和各种 features 都做了详细的说明。

附录

Lint Check 属性

下面这些条目可以用在 allow, warn, deny, forbid 属性中，用于做 Lint 检查（https://doc.rust-lang.org/reference/attributes/diagnostics.html?highlight=rustc,-W#lint-check-attributes）。

$ rustc -W help

Available lint options:
	-W <foo>           Warn about <foo>
	-A <foo>           Allow <foo>
	-D <foo>           Deny <foo>
	-F <foo>           Forbid <foo> (deny <foo> and all attempts to override)


Lint checks provided by rustc:

													   name  default  meaning
													   ----  -------  -------
					 absolute-paths-not-starting-with-crate  allow    fully qualified paths that start with a module name instead of `crate`, `self`, or an extern crate name
									   anonymous-parameters  allow    detects anonymous parameters
											   box-pointers  allow    use of owned (Box type) heap memory
									   deprecated-in-future  allow    detects use of items that will be deprecated in a future version
								  elided-lifetimes-in-paths  allow    hidden lifetime parameters in types are deprecated
							 explicit-outlives-requirements  allow    outlives requirements can be inferred
								  indirect-structural-match  allow    pattern with const indirectly referencing non-`#[structural_match]` type
											 keyword-idents  allow    detects edition keywords being used as an identifier
									 macro-use-extern-crate  allow    the `#[macro_use]` attribute is now deprecated in favor of using macros via the module system
									   meta-variable-misuse  allow    possible meta-variable misuse at macro definition
							   missing-copy-implementations  allow    detects potentially-forgotten implementations of `Copy`
							  missing-debug-implementations  allow    detects missing implementations of fmt::Debug
											   missing-docs  allow    detects missing documentation for public members
								  missing-doc-code-examples  allow    detects publicly-exported items without code samples in their documentation
										   non-ascii-idents  allow    detects non-ASCII identifiers
										  private-doc-tests  allow    detects code samples in docs of private items not documented by rustdoc
									   single-use-lifetimes  allow    detects lifetime parameters that are only used once
											  trivial-casts  allow    detects trivial casts which could be removed
									  trivial-numeric-casts  allow    detects trivial casts of numeric types which could be removed
											unreachable-pub  allow    `pub` items not reachable from crate root
												unsafe-code  allow    usage of `unsafe` code
										  unstable-features  allow    enabling unstable features (deprecated. do not use)
									   unused-extern-crates  allow    extern crates that are never used
									   unused-import-braces  allow    unnecessary braces around an imported item
											  unused-labels  allow    detects labels that are never used
										   unused-lifetimes  allow    detects lifetime parameters that are never used
									  unused-qualifications  allow    detects unnecessarily qualified names
											 unused-results  allow    unused result of an expression in a statement
								   variant-size-differences  allow    detects enums with widely varying variant sizes
										 bare-trait-objects  warn     suggest using `dyn Trait` for trait objects
												  dead-code  warn     detect unused, unexported items
												 deprecated  warn     detects use of deprecated items
						  ellipsis-inclusive-range-patterns  warn     `...` range patterns are deprecated
							  exported-private-dependencies  warn     public interface leaks type from a private dependency
					 illegal-floating-point-literal-pattern  warn     floating-point literals cannot be used in patterns
								 ill-formed-attribute-input  warn     ill-formed attribute inputs that were previously accepted and used in practice
											improper-ctypes  warn     proper use of libc types in foreign modules
										incomplete-features  warn     incomplete features that may function improperly in some or all cases
						  intra-doc-link-resolution-failure  warn     failures in resolving intra-doc link targets
											  invalid-value  warn     an invalid value is being created (such as a NULL reference)
								   irrefutable-let-patterns  warn     detects irrefutable patterns in if-let and while-let statements
							  late-bound-lifetime-arguments  warn     detects generic lifetime arguments in path segments with late bound lifetime parameters
						mutable-borrow-reservation-conflict  warn     reservation of a two-phased borrow conflicts with other shared borrows
										  nested-impl-trait  warn     nested occurrence of `impl Trait` type
									   non-camel-case-types  warn     types, variants, traits and type parameters should have camel case names
							   non-shorthand-field-patterns  warn     using `Struct { x: x }` instead of `Struct { x }` in a pattern
											 non-snake-case  warn     variables, methods, functions, lifetime parameters and modules should have snake case names
									 non-upper-case-globals  warn     static constants should have uppercase identifiers
									no-mangle-generic-items  warn     generic items must be mangled
									   overlapping-patterns  warn     detects overlapping patterns
											path-statements  warn     path statements with no effect
							   patterns-in-fns-without-body  warn     patterns in functions without body were erroneously allowed
										  plugin-as-library  warn     compiler plugin used as ordinary library in non-plugin crate
										  private-in-public  warn     detect private items in public interfaces not caught by the old implementation
					  proc-macro-derive-resolution-fallback  warn     detects proc macro derives using inaccessible names from parent modules
										redundant-semicolon  warn     detects unnecessary trailing semicolons
								  renamed-and-removed-lints  warn     lints that have been renamed or removed
										safe-packed-borrows  warn     safe borrows of fields of packed structs were was erroneously allowed
											stable-features  warn     stable features found in `#[feature]` directive
											 trivial-bounds  warn     these bounds don't depend on an type parameters
										  type-alias-bounds  warn     bounds in type aliases are not enforced
								   tyvar-behind-raw-pointer  warn     raw pointer to an inference variable
									unconditional-recursion  warn     functions that cannot return without calling themselves
											  unknown-lints  warn     unrecognized lint attribute
									  unnameable-test-items  warn     detects an item that cannot be named being marked as `#[test_case]`
										   unreachable-code  warn     detects unreachable code paths
									   unreachable-patterns  warn     detects unreachable patterns
								   unstable-name-collisions  warn     detects name collision with an existing but unstable method
										  unused-allocation  warn     detects unnecessary allocations that can be eliminated
										 unused-assignments  warn     detect assignments that will never be read
										  unused-attributes  warn     detects attributes that were not used by the compiler
										 unused-comparisons  warn     comparisons made useless by limits of the types involved
										unused-doc-comments  warn     detects doc comments that aren't used by rustdoc
											unused-features  warn     unused features found in crate-level `#[feature]` directives
											 unused-imports  warn     imports that are never used
											  unused-macros  warn     detects macros that were not used
											unused-must-use  warn     unused result of a type flagged as `#[must_use]`
												 unused-mut  warn     detect mut variables which don't need to be mutable
											  unused-parens  warn     `if`, `match`, `while` and `return` do not need parentheses
											  unused-unsafe  warn     unnecessary use of an `unsafe` block
										   unused-variables  warn     detect variables which are not used in any way
												   warnings  warn     mass-change the level for lints which produce warnings
								where-clauses-object-safety  warn     checks the object safety of where clauses
												 while-true  warn     suggest using `loop { }` instead of `while true { }`
								 ambiguous-associated-items  deny     ambiguous associated items
												  const-err  deny     constant evaluation detected erroneous expression
									duplicate-macro-exports  deny     detects duplicate macro exports
										exceeding-bitshifts  deny     shift exceeds the type's number of bits
								 invalid-type-param-default  deny     type parameter default erroneously allowed in invalid location
							  legacy-constructor-visibility  deny     detects use of struct constructors that would be invisible with new visibility rules
								 legacy-directory-ownership  deny     non-inline, non-`#[path]` modules (e.g., `mod foo;`) were erroneously allowed in some files not named `mod.rs`
	macro-expanded-macro-exports-accessed-by-absolute-paths  deny     macro-expanded `macro_export` macros from the current crate cannot be referred to by absolute paths
								 missing-fragment-specifier  deny     detects missing fragment specifiers in unused `macro_rules!` patterns
										 mutable-transmutes  deny     mutating transmuted &mut T from &T may cause undefined behavior
									  no-mangle-const-items  deny     const items will not have their symbols exported
							  order-dependent-trait-objects  deny     trait-object types were treated as different depending on marker-trait order
									   overflowing-literals  deny     literal out of range for its type
				  parenthesized-params-in-types-and-modules  deny     detects parenthesized generic parameters in type and module names
							pub-use-of-private-extern-crate  deny     detect public re-exports of private extern crates
										safe-extern-statics  deny     safe access to extern statics was erroneously allowed
											  soft-unstable  deny     a feature gate that doesn't break dependent crates
										unknown-crate-types  deny     unknown crate type found in `#[crate_type]` directive


Lint groups provided by rustc:

name  sub-lints
					   ----  ---------
				   warnings  all lints that are set to issue warnings
		future-incompatible  keyword-idents, anonymous-parameters, illegal-floating-point-literal-pattern, private-in-public, pub-use-of-private-extern-crate, invalid-type-param-default, safe-extern-statics, safe-packed-borrows, patterns-in-fns-without-body, legacy-directory-ownership, legacy-constructor-visibility, missing-fragment-specifier, parenthesized-params-in-types-and-modules, late-bound-lifetime-arguments, order-dependent-trait-objects, tyvar-behind-raw-pointer, absolute-paths-not-starting-with-crate, unstable-name-collisions, duplicate-macro-exports, where-clauses-object-safety, proc-macro-derive-resolution-fallback, macro-expanded-macro-exports-accessed-by-absolute-paths, ill-formed-attribute-input, ambiguous-associated-items, nested-impl-trait, mutable-borrow-reservation-conflict, indirect-structural-match, soft-unstable
		  nonstandard-style  non-camel-case-types, non-snake-case, non-upper-case-globals
	rust-2018-compatibility  keyword-idents, anonymous-parameters, tyvar-behind-raw-pointer, absolute-paths-not-starting-with-crate, duplicate-macro-exports
		   rust-2018-idioms  bare-trait-objects, unused-extern-crates, ellipsis-inclusive-range-patterns, elided-lifetimes-in-paths, explicit-outlives-requirements
					rustdoc  intra-doc-link-resolution-failure, missing-doc-code-examples, private-doc-tests
					 unused  unused-imports, unused-variables, unused-assignments, dead-code, unused-mut, unreachable-code, unreachable-patterns, overlapping-patterns, unused-must-use, unused-unsafe, path-statements, unused-attributes, unused-macros, unused-allocation, unused-doc-comments, unused-extern-crates, unused-features, unused-labels, unused-parens


Compiler plugins can provide additional lints and lint groups. To see a listing of these, re-run `rustc -W help` with a crate filename.