From ebb9a382a4205b343f616cca8bac113abe34aa3a Mon Sep 17 00:00:00 2001 From: The 8472 Date: Tue, 3 Dec 2024 00:53:55 +0100 Subject: [PATCH] document -Zrandomize-layout in the unstable book --- .../src/compiler-flags/randomize-layout.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src/doc/unstable-book/src/compiler-flags/randomize-layout.md diff --git a/src/doc/unstable-book/src/compiler-flags/randomize-layout.md b/src/doc/unstable-book/src/compiler-flags/randomize-layout.md new file mode 100644 index 0000000000000..84c6712bc23a0 --- /dev/null +++ b/src/doc/unstable-book/src/compiler-flags/randomize-layout.md @@ -0,0 +1,23 @@ +# `randomize-layout` + +The tracking issue for this feature is: [#106764](https://github.com/rust-lang/rust/issues/106764). + +------------------------ + +The `-Zrandomize-layout` flag changes the layout algorithm for `repr(Rust)` types defined in the current crate from its normal +optimization goals to pseudorandomly rearranging fields within the degrees of freedom provided by the largely unspecified +default representation. This also affects type sizes and padding. +Downstream intantiations of generic types defined in a crate with randomization enabled will also be randomized. + +It can be used to find unsafe code that accidentally relies on unspecified behavior. + +Randomization is not guaranteed to use a different permutation for each compilation session. +`-Zlayout-seed=` can be used to supply additional entropy. + +Randomization only approximates the intended freedom of repr(Rust). Sometimes two distinct types may still consistently +result in the same layout due to limitations of the current implementation. Randomization may become +more aggressive over time as our coverage of the available degrees of freedoms improves. +Corollary: Randomization is not a safety oracle. Two struct layouts being observably the same under different layout seeds +on the current compiler version does not guarantee that future compiler versions won't give them distinct layouts. + +Randomization may also become less aggressive in the future if additional guarantees get added to the default layout.