Skip to content

Commit 1c676d6

Browse files
committed
Clarify what happens when cfg does not apply
1 parent 2ea22d6 commit 1c676d6

File tree

1 file changed

+27
-0
lines changed

1 file changed

+27
-0
lines changed

text/0000-portability-lint.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,10 @@ The core problem we want to solve is:
174174

175175
- We want to do this *without* requiring testing on platforms that lack the API.
176176

177+
The core idea is that having to write `cfg` is a sufficient speedbump, as it
178+
makes explicit what platform assumptions a piece of code is making. But today,
179+
you don't have to be *within* a `cfg` to call something labeled with `cfg`.
180+
177181
Let's take a concrete example: the `as_raw_fd` method. We'd like to provide this
178182
API as an inherent method on things like files. But it's not a "mainstream" API;
179183
it only works on Unix. If you tried to use it and compiled your code on Windows,
@@ -268,6 +272,29 @@ As with many lints, the portability lint is *best effort*: it is not required to
268272
provide airtight guarantees about portability. However, the RFC sketches a
269273
plausible implementation route that should cover the vast majority of cases.
270274

275+
Note that this lint will only check code that is actually compiled on the
276+
current platform, so the following code would not produce a warning when compiled on `unix`:
277+
278+
```rust
279+
pub fn mycrate_function() {
280+
// ...
281+
}
282+
283+
#[cfg(windows)]
284+
pub fn windows_specific_mycrate_function() {
285+
// this call should warn since it makes an additional assumption
286+
windows_more_specific_mycrate_function();
287+
}
288+
289+
#[cfg(all(windows, target_pointer_width = "64"))]
290+
pub fn windows_more_specific_mycrate_function() {
291+
// ...
292+
}
293+
```
294+
295+
However, any such "missed portability issues" are only possible when already
296+
using `cfg`, which means a "speedbump" has already been passed.
297+
271298
With that overview in mind, let's dig into the details.
272299

273300
## The lint definition

0 commit comments

Comments
 (0)