README.md
1Compiler 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&logo=docs.rs" height="20">](https://docs.rs/rustversion)
7[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/rustversion/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/rustversion/actions?query=branch%3Amaster)
8
9This crate provides macros for conditional compilation according to rustc
10compiler 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]
18rustversion = "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
80Providing additional trait impls as types are stabilized in the standard library
81without breaking compatibility with older compilers; in this case Pin\<P\>
82stabilized 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)]
88use std::pin::Pin;
89
90#[rustversion::since(1.33)]
91impl<P: MyTrait> MyTrait for Pin<P> {
92 /* ... */
93}
94```
95
96Similar but for language features; the ability to control alignment greater than
971 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)))]
104struct Six(i16, i32);
105
106fn main() {
107 println!("{}", std::mem::align_of::<Six>());
108}
109```
110
111Augmenting code with `const` as const impls are stabilized in the standard
112library. This use of `const` as an attribute is recognized as a special case by
113the rustversion::attr macro.
114
115```rust
116use std::time::Duration;
117
118#[rustversion::attr(since(1.32), const)]
119fn duration_as_days(dur: Duration) -> u64 {
120 dur.as_secs() / 60 / 60 / 24
121}
122```
123
124<br>
125
126#### License
127
128<sup>
129Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
1302.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
131</sup>
132
133<br>
134
135<sub>
136Unless you explicitly state otherwise, any contribution intentionally submitted
137for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
138be dual licensed as above, without any additional terms or conditions.
139</sub>
140
