Document #[link_section = "..."] format

[madsmtm]

The values accepted by the link_section attribute is platform-specific, it depends on the binary format.

On most platforms, it just forwards to the linker to do any special stuff with the name IIUC, but for Mach-O, it's a bit different, there LLVM parses the name and sets various flags depending on what the user specified.

For example, the following:

#[unsafe(link_section = "__DATA,my_cstring,cstring_literals,no_toc+no_dead_strip")]
static MY_CSTRING: [u8; 1] = *b"\0";

Results in a binary containing this data:

object::macho::Section64 {
    sectname: "__DATA",
    segname: "my_cstring",
    align: 1,
    reloff: 0,
    nreloc: 0,
    flags: object::macho::S_CSTRING_LITERALS | object::macho::S_ATTR_NO_TOC | object::macho::S_ATTR_NO_DEAD_STRIP,
    // ...
}

That is, the name used in #[link_section] on Mach-O is not inherent to the file format. Therefore, I think we should document what the expected format actually is!

(We should perhaps have had something like #[link_section(segment = "__DATA", segment = "my_cstring", type = "cstring_literals", attributes = ["no_dead_strip", "no_toc"])] on Mach-O instead, but that ship has probably sailed a while ago, I don't think it makes sense to change this).

I discovered this while working on rust-lang/rustc_codegen_cranelift#1648, it turns out that rustc_codegen_cranelift must parse these in the same manner as LLVM to support things like ctor.

Also closely related to rust-lang/rust#155065, it might make sense to expand that parsing to the entire string (to have better control over diagnostics / not be reliant on LLVM changing it).

[madsmtm]

I'll fill these in properly if you think it makes sense to document this in the reference too?

View changes since the review

[madsmtm]

We can leave out the exact names here if you prefer? Though I tend to think it makes sense to have, for example mod_init_funcs is slightly different from what the attribute is documented as in the header (S_MOD_INIT_FUNC_POINTERS).

View changes since the review