]>
Commit | Line | Data |
---|---|---|
6a06907d XL |
1 | # Feature Gates |
2 | ||
3 | This chapter is intended to provide basic help for adding, removing, and | |
4 | modifying feature gates. | |
5 | ||
6 | ||
7 | ## Adding a feature gate | |
8 | ||
9 | See ["Stability in code"] for help with adding a new feature; this section just | |
10 | covers how to add the feature gate *declaration*. | |
11 | ||
12 | Add a feature gate declaration to `rustc_feature/src/active.rs` in the active | |
13 | `declare_features` block: | |
14 | ||
15 | ```rust,ignore | |
16 | /// description of feature | |
17 | (active, $feature_name, "$current_nightly_version", Some($tracking_issue_number), $edition) | |
18 | ``` | |
19 | ||
20 | where `$edition` has the type `Option<Edition>`, and is typically | |
21 | just `None`. | |
22 | ||
23 | For example: | |
24 | ||
25 | ```rust,ignore | |
26 | /// Allows defining identifiers beyond ASCII. | |
27 | (active, non_ascii_idents, "1.0.0", Some(55467), None), | |
28 | ``` | |
29 | ||
136023e0 XL |
30 | Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features` lint] |
31 | by setting their type to `incomplete`: | |
32 | ||
33 | ```rust,ignore | |
34 | /// Allows unsized rvalues at arguments and parameters. | |
35 | (incomplete, unsized_locals, "1.30.0", Some(48055), None), | |
36 | ``` | |
37 | ||
6a06907d XL |
38 | When added, the current version should be the one for the current nightly. |
39 | Once the feature is moved to `accepted.rs`, the version is changed to that | |
40 | nightly version. | |
41 | ||
42 | ||
43 | ## Removing a feature gate | |
44 | ||
45 | [removing]: #removing-a-feature-gate | |
46 | ||
47 | To remove a feature gate, follow these steps: | |
48 | ||
49 | 1. Remove the feature gate declaration in `rustc_feature/src/active.rs`. | |
50 | It will look like this: | |
51 | ||
52 | ```rust,ignore | |
53 | /// description of feature | |
54 | (active, $feature_name, "$version", Some($tracking_issue_number), $edition) | |
55 | ``` | |
56 | ||
57 | 2. Add a modified version of the feature gate declaration that you just | |
58 | removed to `rustc_feature/src/removed.rs`: | |
59 | ||
60 | ```rust,ignore | |
61 | /// description of feature | |
62 | (removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition, | |
63 | Some("$why_it_was_removed")) | |
64 | ``` | |
65 | ||
66 | ||
67 | ## Renaming a feature gate | |
68 | ||
69 | [renaming]: #renaming-a-feature-gate | |
70 | ||
71 | To rename a feature gate, follow these steps (the first two are the same steps | |
72 | to follow when [removing a feature gate][removing]): | |
73 | ||
74 | 1. Remove the old feature gate declaration in `rustc_feature/src/active.rs`. | |
75 | It will look like this: | |
76 | ||
77 | ```rust,ignore | |
78 | /// description of feature | |
79 | (active, $old_feature_name, "$version", Some($tracking_issue_number), $edition) | |
80 | ``` | |
81 | ||
82 | 2. Add a modified version of the old feature gate declaration that you just | |
83 | removed to `rustc_feature/src/removed.rs`: | |
84 | ||
85 | ```rust,ignore | |
86 | /// description of feature | |
87 | /// Renamed to `$new_feature_name` | |
88 | (removed, $old_feature_name, "$version", Some($tracking_issue_number), $edition, | |
89 | Some("renamed to `$new_feature_name`")) | |
90 | ``` | |
91 | ||
92 | 3. Add a feature gate declaration with the new name to | |
93 | `rustc_feature/src/active.rs`. It should look very similar to the old | |
94 | declaration: | |
95 | ||
96 | ```rust,ignore | |
97 | /// description of feature | |
98 | (active, $new_feature_name, "$version", Some($tracking_issue_number), $edition) | |
99 | ``` | |
100 | ||
101 | ||
102 | ## Stabilizing a feature | |
103 | ||
104 | See ["Updating the feature-gate listing"] in the "Stabilizing Features" chapter | |
105 | for instructions. There are additional steps you will need to take beyond just | |
106 | updating the declaration! | |
107 | ||
108 | ||
109 | ["Stability in code"]: ./implementing_new_features.md#stability-in-code | |
136023e0 | 110 | [`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features |
6a06907d | 111 | ["Updating the feature-gate listing"]: ./stabilization_guide.md#updating-the-feature-gate-listing |