document guidelines for which shims have a place in Miri

[RalfJung]

I figured it would be good to document this somewhere, also to ensure we have consensus in the team.
So @rust-lang/miri what do you think -- do you agree with the proposal here?

From what I can tell, all shims we currently have fit the rules described here. We do not use libc or windows-sys or other 3rd-party crates for any of the Miri shims. (We use it for native-lib support, but that's different. It's not something that needs separate work for each shim.)

We did have an flock shim for some time that used libc and windows-sys, but meanwhile std gained APIs for flock so we can use those -- and honestly I think next time I'd prefer to wait until std has APIs; I always felt uneasy about getting enough test coverage for the host part of that implementation, and it invited several PRs where people added more implementations of that for more targets. Miri is IMO not the place to develop a portable HAL for all sorts of random system APIs.

This part here...

we might make exceptions for certain cases if (a) there is a good case
for why Miri should support those APIs, and (b) robust and widely-used portable libraries exist in
the Rust ecosystem

...is foreshadowing: I plan to add support for sockets to Miri, which needs a way to do "wait until any of these file descriptors is ready". I plan to use mio for that, so there will be no platform-dependent code in Miri. I think that is reasonable: mio will not just go away, and it is portable so we don't have to worry about (host) target support in Miri.

We had a similar situation in the past where we used the atty crate to implement, well, atty, which eventually got replaced by the standard library gaining support via is_terminal. That actually did not go so well, atty is unmaintained now. That's why we have to be picky about which crates we use to implement more shims.

[rustbot]

Thank you for contributing to Miri! A reviewer will take a look at your PR, typically within a week or two.
Please remember to not force-push to the PR branch except when you need to rebase due to a conflict or when the reviewer asks you for it.

[RalfJung]

@saethlin @oli-obk any opinion on this? :)

[saethlin]

Miri also has shims for various SIMD intrinsics, or would you not call those shims?

[saethlin]

Suggested change

	implementing every C API ever in Miri.
	implementing every C API ever written in Miri.

[saethlin]

"every C API ever" is fine in informal spoken English, but I think it seems weirdly incomplete in such documentation.