[DRAFT] v0 mangling on nightly #1730
Conversation
| team_url = "https://www.rust-lang.org/governance/teams/compiler" | ||
| +++ | ||
|
|
||
| **TL;DR:** rustc will use its own "v0" mangling scheme by default on nightly |
There was a problem hiding this comment.
| **TL;DR:** rustc will use its own "v0" mangling scheme by default on nightly | |
| **TL;DR:** rustc will use its own "v0" symbol mangling scheme by default on nightly instead of the legacy C++-compatible one |
There was a problem hiding this comment.
I don't think we should say "compatible" because someone might read it as this makes us incompatible with C++. Maybe just "instead of the previous default scheme which reused C++ mangling"?
| In C, the symbol name of a function is just the name that the function was | ||
| defined with, such as `strcmp`. This is straightforward and easy to | ||
| understand, but requires that each item have a globally unique name | ||
| that don't overlap with any symbols from shared libraries that might be linked |
There was a problem hiding this comment.
| that don't overlap with any symbols from shared libraries that might be linked | |
| that don't overlap with any symbols from libraries that it is linked |
| However, rustc is not the only tool that interacts with Rust symbol names: the | ||
| aforementioned debuggers, profilers and other tools all need to be updated to | ||
| understand Rust's v0 symbol mangling scheme so that Rust's users can continue | ||
| to work with Rust binaries using all the tools they're used to. Furthermore, all |
There was a problem hiding this comment.
| to work with Rust binaries using all the tools they're used to. Furthermore, all | |
| to work with Rust binaries using all the tools they're used to without having to look at mangled symbols. Furthermore, all |
| ``` | ||
|
|
||
| With the legacy mangling scheme, all of the useful information about the generic | ||
| instantiation of `foo` is lost in the symbol `f:foo`.. |
There was a problem hiding this comment.
| instantiation of `foo` is lost in the symbol `f:foo`.. | |
| instantiation of `foo` is lost in the symbol `f::foo`.. |
|
|
||
| Symbols using the v0 mangling scheme can be larger than symbols with the | ||
| legacy mangling scheme, which can result in a slight increase in linking | ||
| times. Fortunately this impact should be minor, especially with modern |
There was a problem hiding this comment.
| times. Fortunately this impact should be minor, especially with modern | |
| times and binary sizes if symbols aren't stripped (which they aren't by default). Fortunately this impact should be minor, especially with modern |
|
|
||
| Some old versions of tools/distros or niche tools that the compiler team are | ||
| unaware of may not have had support for the v0 mangling scheme added. | ||
|
|
There was a problem hiding this comment.
It should be mentioned explicitly that the consequences here are having to look at mangled symbols, which isn't great but also not completely terrible.
There was a problem hiding this comment.
And maybe mention https://github.com/luser/rustfilt as a fallback? I think it can handle v0 mangling?
|
leaving comments would have been easier if you used semantic line breaks instead of hard wrapping at a column count :) |
| In C, the symbol name of a function is just the name that the function was | ||
| defined with, such as `strcmp`. This is straightforward and easy to | ||
| understand, but requires that each item have a globally unique name | ||
| that don't overlap with any symbols from shared libraries that might be linked |
There was a problem hiding this comment.
| that don't overlap with any symbols from shared libraries that might be linked | |
| that doesn't overlap with any symbols from shared libraries that might be linked |
| rustc book for our current documentation on the format). Our "v0" mangling scheme has | ||
| multiple advantageous properties: | ||
|
|
||
| - An unambigious encoding for everything that can end up in a binary's symbol table |
There was a problem hiding this comment.
| - An unambigious encoding for everything that can end up in a binary's symbol table | |
| - An unambiguous encoding for everything that can end up in a binary's symbol table |
| Languages like Rust and C++ define "symbol mangling schemes", leveraging information | ||
| from the type system to give each item a unique symbol name. Otherwise every | ||
| instantiation of a generic or templated function (or an overload in C++), which has | ||
| the same name in the surface language would end up with clashing symbols. |
There was a problem hiding this comment.
Feels like this should mention paths vs identifiers, e.g. Rust lets you have a::foo and b::foo. It's not just generics.
| unaware of may not have had support for the v0 mangling scheme added. | ||
|
|
||
| In any case, using the new mangling scheme can be disabled if any problem | ||
| occurs: use the `-Csymbol-mangling-version=legacy -Zunstable-options` flag |
There was a problem hiding this comment.
Why is the -Zunstable-options needed? It's surprising/unfortunate it's needed for legacy but not needed for v0.
There was a problem hiding this comment.
The legacy mangling scheme is unstable (and might stay unstable, I guess to be decided).
There was a problem hiding this comment.
It feels very odd that the mangling scheme that has been used forever is unstable. Maybe that warrants more explanation?
| occurs: use the `-Csymbol-mangling-version=legacy -Zunstable-options` flag | ||
| to revert to using the legacy mangling scheme. | ||
|
|
||
| #### Summary |
There was a problem hiding this comment.
I think we should have a section for tool owners that want to add support pointing at rustc-demangle which has a C and Rust implementation of the v0 demangler, which hopefully makes it easier for people to quickly add support if they find it's missing.
(I can try to write some text later, don't have time right this moment).
6 participants
Blog post for rust-lang/compiler-team#938 once that MCP completes
Rendered