Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
madsmtm wants to merge 3 commits into
base: master
Choose a base branch
from
+68 −3
Open

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

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5b7857d
Document Mach-O link section format
madsmtm Apr 19, 2026
a731f87
WIP: Begin documenting other link section formats
madsmtm Apr 19, 2026
8446a19
Showcase platform-specificness in link_section example
madsmtm Apr 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Document Mach-O link section format
  • Loading branch information
@madsmtm
madsmtm committed Apr 19, 2026
commit 5b7857dc86bc8d20e81cd8b16891b5728a3f16f3
35 changes: 35 additions & 0 deletions src/abi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,41 @@ r[abi.link_section.edition2024]
> [!EDITION-2024]
> Before the 2024 edition it is allowed to use the `link_section` attribute without the `unsafe` qualification.

r[abi.link_section.format]
The format of the `link_section` attribute is platform-specific, and the
supported options varies depending on the underlying object file format.

r[abi.link_section.mach-o]
### Link section Mach-O format

<!-- Parsing done by LLVM in https://github.com/llvm/llvm-project/blob/llvmorg-22.1.3/llvm/lib/MC/MCSectionMachO.cpp -->
Copy link
Copy Markdown
Contributor Author

@madsmtm madsmtm Apr 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

View changes since the review

r[abi.link_section.mach-o.syntax]
```grammar,attributes
MachOLinkSection -> MachOSegment `,` MachOSection (`,` (MachOSectionType (`,` MachOSectionAttributes?)?)?)?

MachOLinkSectionStub -> MachOSegment `,` MachOSection `,` `symbol_stubs` `,` MachOSectionAttributes? `,` MachOSectionStubSize

MachOSegment -> <0 to 16 bytes>

MachOSection -> <1 to 16 bytes>

MachOSectionType -> `regular` | `zerofill` | `cstring_literals` | `4byte_literals` | `8byte_literals` | `literal_pointers` | `non_lazy_symbol_pointers` | `lazy_symbol_pointers` | `mod_init_funcs` | `mod_term_funcs` | `coalesced` | `interposing` | `16byte_literals` | `thread_local_regular` | `thread_local_zerofill` | `thread_local_variables` | `thread_local_variable_pointers` | `thread_local_init_function_pointers`
Copy link
Copy Markdown
Contributor Author

@madsmtm madsmtm Apr 19, 2026 •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


MachOSectionAttributes -> MachOSectionAttribute (`+` MachOSectionAttribute)*

MachOSectionAttribute -> `pure_instructions` | `no_toc` | `strip_static_syms` | `no_dead_strip` | `live_support` | `self_modifying_code` | `debug`

MachOSectionStubSize -> DEC_DIGIT (DEC_DIGIT)*
```

r[abi.link_section.mach-o.intro]
The link section format string on Mach-O has five configurable fields: the
segment, the section, the section type, the section attributes and the stub
size (if the `symbol_stubs` section type is used).

r[abi.link_section.mach-o.default-type]
The section type defaults to `regular` if not set.

r[abi.export_name]
## The `export_name` attribute

Expand Down