You should document (or link documentation for) your list of supported ABIs

[mcclure]

I am reading the Rust reference. In section 6.4 it notes a function may be augmented with an extern "something" prefix to make it use the "something" function ABI. It mentions "Rust", "C", and "stdcall" as examples. However, it does not list what ABIs are allowed.

I do not expect the Rust reference to document all of the allowed ABIs, because the Rust reference says in the introduction "this book does not usually document the specifics of rustc as a tool... rustc has its own book". I would expect the list of allowed extern ABIs to be an implementation detail of the compiler, rustc or otherwise, and probably not appropriate for the reference (unless those ABIs are a required feature of all compliant Rust compilers). However, if I go to the rustc book and search, using the magnifying glass icon at the top, for "abi" I do not find anything like a list of supported ABIs.

I asked for help finding an ABI list on "Twitter". I got two responses of places I should look, which I found unsatisfying:

• A couple people linked this abi.rs file in the Rust source. This source is semi-obviously not adequate documentation even if someone knows how to find it, in particular the big enum at the top differs in things like capitalization from how the "abi" strings are formatted.
• It turns out within the reference there is another section, 6.13, on external blocks, which does have a list of allowed ABI strings. However there are three problems with this section: One, although 6.4 incidentally links 6.13 it does not indicate 6.13 contains the ABI list, which would make this list hard to find if one is reading the reference guide linearly (or nonlinearly but happening to read 6.4 before 6.13); two, the list in 6.13 does not indicate which platforms each of the ABIs is available on (for example it notes "stdcall" is the default for the "system" alias on x86_32 Windows, but doesn't indicate whether it is allowed on x86_64); and three, as the person on Twitter who helped me find this list pointed out, it doesn't list ABIs which are currently allowed but unstable.

My "Expected Behavior" is:

• There should be, somewhere in the world, a document listing all the ABI strings which are allowed in a function extern or block extern {} in official rustc. The list should indicate for each string which platforms it is currently available on. If a string is unstable or may be removed in future, it should be listed, but marked as unstable. In my personal opinion the most sensible place for this list to be would be in the rustc book.
• If the list is somewhere in the world other than the rustc book (which the reference manual calls out early as containing additional information), rustc reference section 6.4 "functions" should link that list (or 6.13 should link it and 6.4 should link 6.13).
• If section 6.13 is going to contain normative text that changes the interpretation of 6.4 (which it currently does: "there are three ABI strings which are cross-platform, and which all compilers are guaranteed to support"), then 6.4 should contain a link to 6.13 explicitly labeled with "more information on supported ABI strings is in section 6.13" (or something).

IMO

[eddyb]

This source is semi-obviously not adequate documentation even if someone knows how to find it, in particular the big enum at the top differs in things like capitalization from how the "abi" strings are formatted.

While not obvious, and clearly not a replacement for documentation, if you scroll down a bit there's this list which includes the names used in the extern "..." syntax. If I had to guess, extern "C unwind" is handled with a different mechanism entirely.

(Also, if only we hadn't used extern "..." syntax for ABIs... the string literal based system is a mess)

[chorman0773]

I would assume that the full list of supported abis is an implementation-defined (or unspecified) set that contains "Rust", "C", and "system". If this is the case, I would recommend the reference document that, and then perhaps give examples of some additionally abis that rustc supports, but would be a good idea to implement in general when applicable (probably at least the Win32 list, "sysv64", and "win64").
Would it also be a good idea to state that the supported abis for function items does not need to be the same as those supported for extern blocks?

[Havvy]

We should definitely list out the ABIs that every implementation should have. Is it just "Rust", "C", and "System", or are there more?

[mcclure]

We should definitely list out the ABIs that every implementation should have. Is it just "Rust", "C", and "System", or are there more?

You do exactly this in section 6.13, which is good, but there's no indication reading 6.4 that this is the case or that you need to check 6.13 for this kind of information. (The three ABIs you list in your comment are the exact three 6.13 says is required.)

chorman0773 above raises the possibility that "the supported abis for function items does not need to be the same as those supported for extern blocks". Is that actually true?

If the set of additional ABIs besides the required three is "implementation-defined", that is fine, but if that is the case then rustc needs to document the full set, since it is an implementation. If issues on the "rustc book" need to be filed on the rustc book's github page I do not know where that is.

[Havvy]

The rustc book is in the main Rust repo here. I've raised this issue on Zulip to see what the people on the compiler think.

(I should also probably say I've mostly ignored ABI stuff, so I'm ignorant about many things here. Don't take what I say personally as a voice of an expert.)

[chorman0773]

On Tue, Mar 9, 2021 at 20:06 mcclure ***@***.***> wrote: We should definitely list out the ABIs that every implementation should have. Is it just "Rust", "C", and "System", or are there more? You do exactly this in section 6.13, which is good, but there's no indication reading 6.4 that this is the case or that you need to check 6.13 for this kind of information. (The three ABIs you list are the exact three 6.13 says is required.) chorman0773 above raises the possibility that "the supported abis for function items does not need to be the same as those supported for extern blocks". Is that actually true?

I do not believe it's valid to define a function that is extern"rust-intrinsic", even with the appropriate feature turned on. Likewise, I also don't believe that extern"rust-call" blocks are allowed, even with unboxed_closures. While both cases are unstable, this would still fall under "implementation-defined".

If the set of additional ABIs besides the required three is "implementation-defined", that is fine, but if that is the case then *rustc* needs to document the full set, since it is an implementation. If issues on the "rustc book" need to be filed on the rustc book's github page I do not know where that is.

~~I believe it is already documented by rustc.~~ Scratch that, I am incorrect about that.

…

— You are receiving this because you commented. Reply to this email directly, view it on GitHub <#975 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABGLD26TEUDHZG75TED6MOLTC2ZWTANCNFSM4YYL24TA> .

[mcclure]

If it's legal for the set of ABI strings accepted by an implementation to be different for a function decl than for an extern "..." { }, then definitely I think either 6.4 or 6.13 should make that clear.

[ben0x539]

To me it'd seem more natural to list the ABIs in the page on functions, and have the extern blocks page point at that (and it seems like we can do that independently of any changes of how we present platform-specific ABIs). Does that sound right?