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).

---

An alternative here would be to:

• Document this on the Clang attribute instead. (Or possibly somewhere in LLVM's LangRef).
• Document this in Cranelift.
• Link to the support in each of those.

I'd be fine with that too, if you think that's better?

[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

[madsmtm]

I checked what GCC does here, it seems to pass the section onwards to the assembler unchanged (i.e. forwards the problem to the assembler). On most GCC installations on macOS, the default assembler is LLVM's (so it supports the same syntax as documented here).

A few other assemblers:

• Apple's old, deleted assembler cctools/as supported a subset of these in the same format: https://github.com/apple-oss-distributions/cctools/blob/cctools-1010.6/as/read.c#L232-L279
• NASM has it's own (more limited) syntax: https://github.com/netwide-assembler/nasm/blob/aa12d3381a1fd08e72f594147f2486c1b5ab7813/output/outmacho.c#L739-L748 (though they still use the same comma-separated format for segments and sections)

View changes since the review