rustc book should document the ABIs rustc supports

[mcclure]

I am learning Rust. While reading the Rust reference, I learned about the interesting "ABI" feature, where extern "anystring" before a function or { } bare block containing functions will declare functions using a special ABI other than "Rust". However I found a problem, which is that there was no list of ABI strings. The reference has a partial list of ABIs but it is incomplete and does not clarify on what platforms those ABI strings are supported.

I created an issue about this on the Reference repo and after some discussion my opinion, as well as what I perceive to be the consensus in that issue thread, is that the most appropriate place to document the ABI strings would be the rustc book. (There are some ABIs already documented in the reference which are appropriate for callout in the reference— three ABIs "Rust" "C" "system" which all implementations are required to implement, and several defined ABIs that "system" is guaranteed to alias to— but other than those language-reference-required ABIs, which ABI strings are supported and what they do are implementation-defined. As rustc is an implementation [the implementation] this means that the complete list should be documented by rustc.)

However if I look in the rustc book and search the book for the word "abi", I find no discussion of the ABI strings.

Apparently people who need this information currently are consulting the Rust source directly, but I feel strongly the source is not an adequate replacement for documentation as it is difficult to find, difficult to read, and contains no details about where the ABIs are available or what they do.

My "expected behavior" is that there should be a section defining the full list of rustc's supported ABI strings in the rustc book, probably a top-level section or a subsection under section 6. For each ABI, this section should list:

• What does the ABI do?
• On what platforms and ISAs (x86_32 Windows, x86_64 Windows, Mac, etc) is the ABI available?
• Is the ABI legal on function items or only extern blocks? (For example it was explained to me in the Rust reference issue that ABI "rust-intrinsic" is only allowed on extern blocks.)
• Is support for the ABI stable or unstable? (The Rust reference does not document unstable language features because it is paired with an entire separate book documenting the unstable features, but the rustc book does not have this kind of split and has nowhere else documentation for the unstable features could go.)

[steveklabnik]

(Tagging with the compiler and lang teams; I imagine the compiler will want to document the ABIs supported no matter what, and the lang team may want to weigh in on if any of them are required by any implementation or if it's entirely implementation defined. I don't imagine such a decision would be made here, but maybe some thoughts would help the compiler team write this up.)

[ehuss]

The reference has a partial list of ABIs

There should be a complete list at https://doc.rust-lang.org/nightly/reference/items/external-blocks.html#abi. They are not documented well, but that can be fixed. All other ABIs are unstable, and should be documented in
the unstable book (like https://doc.rust-lang.org/nightly/unstable-book/language-features/c-unwind.html). If there is documentation missing there, that can be fixed.

the most appropriate place to document the ABI strings would be the rustc book

I don't agree with this position (at least not yet). I think either they should be part of the language, not some halfway rustc-only thing (unless it is a nightly only feature).

I think it definitely would be helpful to have more advanced documentation that explain how and why different ABIs are used, but I'm not sure the rustc book is the place for that.