]>
Commit | Line | Data |
---|---|---|
f20569fa XL |
1 | Compiler version cfg |
2 | ==================== | |
3 | ||
4 | [<img alt="github" src="https://img.shields.io/badge/github-dtolnay/rustversion-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/rustversion) | |
5 | [<img alt="crates.io" src="https://img.shields.io/crates/v/rustversion.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/rustversion) | |
6 | [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-rustversion-66c2a5?style=for-the-badge&labelColor=555555&logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDUxMiA1MTIiPjxwYXRoIGZpbGw9IiNmNWY1ZjUiIGQ9Ik00ODguNiAyNTAuMkwzOTIgMjE0VjEwNS41YzAtMTUtOS4zLTI4LjQtMjMuNC0zMy43bC0xMDAtMzcuNWMtOC4xLTMuMS0xNy4xLTMuMS0yNS4zIDBsLTEwMCAzNy41Yy0xNC4xIDUuMy0yMy40IDE4LjctMjMuNCAzMy43VjIxNGwtOTYuNiAzNi4yQzkuMyAyNTUuNSAwIDI2OC45IDAgMjgzLjlWMzk0YzAgMTMuNiA3LjcgMjYuMSAxOS45IDMyLjJsMTAwIDUwYzEwLjEgNS4xIDIyLjEgNS4xIDMyLjIgMGwxMDMuOS01MiAxMDMuOSA1MmMxMC4xIDUuMSAyMi4xIDUuMSAzMi4yIDBsMTAwLTUwYzEyLjItNi4xIDE5LjktMTguNiAxOS45LTMyLjJWMjgzLjljMC0xNS05LjMtMjguNC0yMy40LTMzLjd6TTM1OCAyMTQuOGwtODUgMzEuOXYtNjguMmw4NS0zN3Y3My4zek0xNTQgMTA0LjFsMTAyLTM4LjIgMTAyIDM4LjJ2LjZsLTEwMiA0MS40LTEwMi00MS40di0uNnptODQgMjkxLjFsLTg1IDQyLjV2LTc5LjFsODUtMzguOHY3NS40em0wLTExMmwtMTAyIDQxLjQtMTAyLTQxLjR2LS42bDEwMi0zOC4yIDEwMiAzOC4ydi42em0yNDAgMTEybC04NSA0Mi41di03OS4xbDg1LTM4Ljh2NzUuNHptMC0xMTJsLTEwMiA0MS40LTEwMi00MS40di0uNmwxMDItMzguMiAxMDIgMzguMnYuNnoiPjwvcGF0aD48L3N2Zz4K" height="20">](https://docs.rs/rustversion) | |
7 | [<img alt="build status" src="https://img.shields.io/github/workflow/status/dtolnay/rustversion/CI/master?style=for-the-badge" height="20">](https://github.com/dtolnay/rustversion/actions?query=branch%3Amaster) | |
8 | ||
9 | This crate provides macros for conditional compilation according to rustc | |
10 | compiler version, analogous to [`#[cfg(...)]`][cfg] and | |
11 | [`#[cfg_attr(...)]`][cfg_attr]. | |
12 | ||
13 | [cfg]: https://doc.rust-lang.org/reference/conditional-compilation.html#the-cfg-attribute | |
14 | [cfg_attr]: https://doc.rust-lang.org/reference/conditional-compilation.html#the-cfg_attr-attribute | |
15 | ||
16 | ```toml | |
17 | [dependencies] | |
18 | rustversion = "1.0" | |
19 | ``` | |
20 | ||
21 | <br> | |
22 | ||
23 | ## Selectors | |
24 | ||
25 | - <b>`#[rustversion::stable]`</b> | |
26 | —<br> | |
27 | True on any stable compiler. | |
28 | ||
29 | - <b>`#[rustversion::stable(1.34)]`</b> | |
30 | —<br> | |
31 | True on exactly the specified stable compiler. | |
32 | ||
33 | - <b>`#[rustversion::beta]`</b> | |
34 | —<br> | |
35 | True on any beta compiler. | |
36 | ||
37 | - <b>`#[rustversion::nightly]`</b> | |
38 | —<br> | |
39 | True on any nightly compiler or dev build. | |
40 | ||
41 | - <b>`#[rustversion::nightly(2019-01-01)]`</b> | |
42 | —<br> | |
43 | True on exactly one nightly. | |
44 | ||
45 | - <b>`#[rustversion::since(1.34)]`</b> | |
46 | —<br> | |
47 | True on that stable release and any later compiler, including beta and | |
48 | nightly. | |
49 | ||
50 | - <b>`#[rustversion::since(2019-01-01)]`</b> | |
51 | —<br> | |
52 | True on that nightly and all newer ones. | |
53 | ||
54 | - <b>`#[rustversion::before(`</b><i>version or date</i><b>`)]`</b> | |
55 | —<br> | |
56 | Negative of *#[rustversion::since(...)]*. | |
57 | ||
58 | - <b>`#[rustversion::not(`</b><i>selector</i><b>`)]`</b> | |
59 | —<br> | |
60 | Negative of any selector; for example *#[rustversion::not(nightly)]*. | |
61 | ||
62 | - <b>`#[rustversion::any(`</b><i>selectors...</i><b>`)]`</b> | |
63 | —<br> | |
64 | True if any of the comma-separated selectors is true; for example | |
65 | *#[rustversion::any(stable, beta)]*. | |
66 | ||
67 | - <b>`#[rustversion::all(`</b><i>selectors...</i><b>`)]`</b> | |
68 | —<br> | |
69 | True if all of the comma-separated selectors are true; for example | |
70 | *#[rustversion::all(since(1.31), before(1.34))]*. | |
71 | ||
72 | - <b>`#[rustversion::attr(`</b><i>selector</i><b>`, `</b><i>attribute</i><b>`)]`</b> | |
73 | —<br> | |
74 | For conditional inclusion of attributes; analogous to `cfg_attr`. | |
75 | ||
76 | <br> | |
77 | ||
78 | ## Use cases | |
79 | ||
80 | Providing additional trait impls as types are stabilized in the standard library | |
81 | without breaking compatibility with older compilers; in this case Pin\<P\> | |
82 | stabilized in [Rust 1.33][pin]: | |
83 | ||
84 | [pin]: https://blog.rust-lang.org/2019/02/28/Rust-1.33.0.html#pinning | |
85 | ||
86 | ```rust | |
87 | #[rustversion::since(1.33)] | |
88 | use std::pin::Pin; | |
89 | ||
90 | #[rustversion::since(1.33)] | |
91 | impl<P: MyTrait> MyTrait for Pin<P> { | |
92 | /* ... */ | |
93 | } | |
94 | ``` | |
95 | ||
96 | Similar but for language features; the ability to control alignment greater than | |
97 | 1 of packed structs was stabilized in [Rust 1.33][packed]. | |
98 | ||
99 | [packed]: https://github.com/rust-lang/rust/blob/master/RELEASES.md#version-1330-2019-02-28 | |
100 | ||
101 | ```rust | |
102 | #[rustversion::attr(before(1.33), repr(packed))] | |
103 | #[rustversion::attr(since(1.33), repr(packed(2)))] | |
104 | struct Six(i16, i32); | |
105 | ||
106 | fn main() { | |
107 | println!("{}", std::mem::align_of::<Six>()); | |
108 | } | |
109 | ``` | |
110 | ||
111 | Augmenting code with `const` as const impls are stabilized in the standard | |
112 | library. This use of `const` as an attribute is recognized as a special case by | |
113 | the rustversion::attr macro. | |
114 | ||
115 | ```rust | |
116 | use std::time::Duration; | |
117 | ||
118 | #[rustversion::attr(since(1.32), const)] | |
119 | fn duration_as_days(dur: Duration) -> u64 { | |
120 | dur.as_secs() / 60 / 60 / 24 | |
121 | } | |
122 | ``` | |
123 | ||
124 | <br> | |
125 | ||
126 | #### License | |
127 | ||
128 | <sup> | |
129 | Licensed under either of <a href="LICENSE-APACHE">Apache License, Version | |
130 | 2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. | |
131 | </sup> | |
132 | ||
133 | <br> | |
134 | ||
135 | <sub> | |
136 | Unless you explicitly state otherwise, any contribution intentionally submitted | |
137 | for inclusion in this crate by you, as defined in the Apache-2.0 license, shall | |
138 | be dual licensed as above, without any additional terms or conditions. | |
139 | </sub> |