document that target features are unsafe

[nikomatsakis]

When discussing #63466 in the compiler team triage meeting, it became clear that target-features ought to be considered generally unsafe. We should document this fact in the -Chelp and in the rustc book. Ideally, we'd also start listing out known gotchas.

For example, in #63466 @nikic noted that:

#63466 (comment)

and @rkruppe had a much more detailed comment.

This issue has been assigned to @togiberlin via this comment.

[nikomatsakis]

Compiler triage meeting:

Marking as P-medium

[togiberlin]

@rustbot claim

[gnzlbg]

The reference section about Behavior considered undefined mentions this:

Executing code compiled with platform features that the current platform does not support (see target_feature).

The link to the target_feature section of the reference mentions this as well:

It is undefined behavior to call a function that is compiled with a feature that is not supported on the current platform the code is running on.

So maybe the -C help could point people to the reference?

[hanna-kruppe]

That is one way in which target_feature is unsafe, but it's not the one which was the subject of #63466 so just pointing at the reference as it is is insufficient. Plus, it's also more about -C target-feature than #[target_feature] (where the compiler will hit you in the face with unsafe). So the rustc book is a better place for it than the reference IMO.

[gnzlbg]

I think that for users to better properly understand the UB involved, it might be more educational to say that -C target-feature=+X stamps #[target_feature(enable = "X")] on all functions, but with the subtle difference that it doesn't make them unsafe fn, so no unsafe-check happens when this triggers UB.

The reference does not document all current perils of using #[target_feature(enable = "X")]. In particular, it does not document that these can change the function call ABI, and that rustc neither checks that nor handles it correctly - we just currently assume people don't do that.

Independently of whether we document that in the rustc book as well or not, that bit should also probably be documented in the reference, because it is easy to trigger this. On stable Rust, I think one can indeed only trigger this via -C target-feature and the reference should say so, but on nightly one can definitely trigger this with bare #[target_feature(enable = "...")] within a single Rust crate.