Document --show-type-layout in the rustdoc book
#89164
Conversation
camelid
added
A-docs
rust-highfive
added
the
S-waiting-on-review
|
See also the discussion on Discord. |
| When this flag is passed, rustdoc will add a "Layout" section at the bottom of | ||
| each type's docs page that includes a summary of the type's memory layout as | ||
| computed by rustc. For example, rustdoc will show the size in bytes that a value | ||
| of that type will take in memory. |
There was a problem hiding this comment.
Why do you say "for example"? Isn't that the only part of the layout it shows?
There was a problem hiding this comment.
No, it also shows the size of each variant. The things it displays could change later, so I'd rather not have an exhaustive list that needs to be updated.
| @@ -1663,7 +1663,7 @@ fn document_type_layout(w: &mut Buffer, cx: &Context<'_>, ty_def_id: DefId) { | |||
| writeln!( | |||
| w, | |||
| "<div class=\"warning\"><p><strong>Note:</strong> Most layout information is \ | |||
| completely unstable and may be different between compiler versions and platforms. \ | |||
| completely unstable and may even differ between compilations. \ | |||
There was a problem hiding this comment.
How can this be true? The compiler has to be able to depend on the ABI to create dynamic libraries.
There was a problem hiding this comment.
From the Reference (emphasis mine):
Type layout can be changed with each compilation. Instead of trying to document exactly what is done, we only document what is guaranteed today.
I assume that means that the compiler is free to change layout if your crate is a static library or a binary. Also, there are (future) flags like -Z randomize-layout which would change layout between compilations.
|
r=me with CI passing Thanks for documenting this! |
|
@bors r=jyn514 rollup |
|
📌 Commit fcb837b has been approved by |
bors
added
S-waiting-on-bors
…n514 Document `--show-type-layout` in the rustdoc book I also made a few small, related changes as separate commits. r? `@jyn514`
Rollup of 8 pull requests Successful merges: - rust-lang#89036 (Fix missing `no_global_oom_handling` cfg-gating) - rust-lang#89041 (Work around invalid DWARF bugs for fat LTO) - rust-lang#89046 ("Fix" an overflow in byte position math) - rust-lang#89127 (Re-enable the `src/test/debuginfo/mutex.rs` test on Windows) - rust-lang#89133 (Fix ICE with `--cap-lints=allow` and `-Zfuel=...=0`) - rust-lang#89162 (rustc_index: Add some map-like APIs to `IndexVec`) - rust-lang#89164 (Document `--show-type-layout` in the rustdoc book) - rust-lang#89170 (Disable the leak sanitizer on Macos aarch64 for now) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
I also made a few small, related changes as separate commits.
r? @jyn514