Unify OsStringExt/OsStrExt traits across platforms

[thaliaarchi]

Currently, the std::os::{platform}::ffi::{OsStringExt, OsStrExt} traits have quite a bit of duplication, since there are several platforms using only three implementations of OsString/OsStr (bytes, WTF-8, and recently now UTF-8). To deal with this, the bytes platforms reexport the Unix ext traits, but provide their own module-level documentation. This documentation has grown slightly out of sync and some platforms forgot to include it entirely. UEFI, as it has much shared background with Windows, simply reexports the whole Windows ffi module.

Move these modules to std::sys::ffi::{bytes, windows, utf8} and publicly reexport them as each platform's std::os::{platform}::ffi module. To handle the differing documentation, use cfg_select!. The bytes impl has the examples in the module docs, to be reused, but could now be moved to the relevant traits. Since the Windows docs have much Windows-specific wording, I have named that module windows instead of wtf8, but if UEFI wants to grow its own documentation, we could rename it to wtf8 and create conditionally-included Markdown files for both, as I assume it would have many changes. For now, utf8 has Motor OS–specific docs, but I intend to generalize it when I add WASIp2 and Redox OS support (see #147932).

This is related to the effort in #117276, but takes a different approach by necessity of the traits and documentation being public, instead of an internal abstraction layer. I think it turned out reasonably and is better than what we currently have, but I am open to other approaches. The primary downside is that there are cfg gates that must be kept in sync in two places: in library/core/src/os/mod.rs and the docs of library/std/src/sys/ffi/bytes.rs.

The two-step diff makes it slightly more clear that the Unix traits were not changed; only moved.

r? @joboet

[rustbot]

joboet is currently at their maximum review capacity.
They may take a while to respond.

[hkBst]

LGTM, but probably should go through try-run to catch problems on more platforms.

View changes since this review

[thaliaarchi]

probably should go through try-run to catch problems on more platforms.

I x checked it against this set of targets (the targets that have their own PALs), but a try run would be good for others' peace of mind.

[build]
host = ["x86_64-unknown-linux-gnu"]
target = [
    "x86_64-unknown-linux-gnu",
    "aarch64-apple-darwin", "x86_64-apple-darwin",
    "aarch64-unknown-fuchsia", "x86_64-unknown-fuchsia",
    "x86_64-unknown-hermit", "aarch64-unknown-hermit", "aarch64_be-unknown-hermit", "riscv64gc-unknown-hermit",
    "x86_64-unknown-motor",
    "x86_64-unknown-redox", "aarch64-unknown-redox", "i586-unknown-redox",
    "x86_64-fortanix-unknown-sgx",
    "aarch64-kmc-solid_asp3", "armv7a-kmc-solid_asp3-eabi", "armv7a-kmc-solid_asp3-eabihf",
    "aarch64-unknown-teeos",
    "aarch64-unknown-trusty", "armv7-unknown-trusty",
    "x86_64-unknown-uefi", "aarch64-unknown-uefi", "i686-unknown-uefi",
    "armv7a-vex-v5",
    "wasm32-unknown-unknown", "wasm32v1-none", "wasm32-wasip1", "wasm32-wasip1-threads", "wasm32-wasip2", "wasm32-wasip3", "wasm32-wali-linux-musl", "wasm32-unknown-emscripten", "wasm64-unknown-unknown",
    "x86_64-pc-windows-gnu",
    "riscv32imac-unknown-xous-elf",
    "riscv32im-risc0-zkvm-elf",
]

[ChrisDenton]

This needn't be a blocker but I'm personally not a fan of using #[path] except as a last resort. Is there no way to use the normal import system for this?

[thaliaarchi]

I suppose the platforms could use it than pub use it. It might need a docs collapse or whatever. I’m not convinced it’ll turn out better, only more verbose. It’s used frequently in std::sys, but, yeah, this case is public. Is this for tooling reasons?
I’ll try that in a week when I’m not at the LLVM meeting

[thaliaarchi]

There’s a significant downside: all cfg_select!s would be active for all platforms, not just the platforms intended for a given module, so they’d need fallthrough cases, which would break the static checking

[ChrisDenton]

Ah that is a significant downside, yeah. In that case I don't hate it enough to insist but I am sad that it's necessary.