Repository: rust
Issue: Support auto linking on Apple targets
Labels: A-linkage,O-macos,T-compiler

## Problem statement

Using a statically compiled Rust library from another language / with other toolchains can be somewhat troublesome, since the Rust library may have linking requirements that the user then has to manually pass to the linker.

Specific example: I have a static Rust library compiled for macOS that uses Winit and Wgpu and exposes a `rust_main` function, which I then pass to Xcode to link together with a small C main file that calls into Rust. Under the hood, Winit/Wgpu requires linking to `AppKit`, `Metal` and other such system frameworks. I'm required to also specify in Xcode the frameworks that my binary requires.

Apart from being difficult to set up (as I, the user, has to know enough about linking to understand the inscrutable error messages), this workflow is also a possible SemVer hazard, as a library like Winit cannot add a dependency on a new the system library in a minor version without possibly breaking the user's build.

This can be fixed by using the `--print=native-static-libs` `rustc` flag, but that probably requires more work for the user to integrate into the workflow than the quick fix of "just link to the broken library", and is also not very discoverable.


## Proposed solution

Swift and Clang have the concept of "auto linking", where the compiler will instruct the linker to link to the correct external libraries if the user imports code from one of these libraries. This is enabled in Clang with `-fmodules`, and can be further controlled with the [`-fno-autolink`](https://clang.llvm.org/docs/Modules.html#command-line-parameters) flag, or manually inserted with `-Xclang --linker-option=xyz`.

On the surface, this provides much the same functionality as Rust with its `#[link(...)]` attribute, but there's an important distinction: **the dependency information is embedded in the object file, and understood by the linker itself**, which allows it to work without Swift/Clang driving the linker invocation!

This would fix https://github.com/rust-lang/rust/issues/110143.


## Implementation notes

Mach-O binaries uses the `LC_LINKER_OPTION` load command for this, which is understood by LLVM's lld, and Apple's ld64. A few resources on that:
- <https://milen.me/writings/auto-linking-on-ios-and-macos/>
- <https://github.com/qyang-nj/llios/blob/main/macho_parser/docs/LC_LINKER_OPTION.md>
- <https://github.com/aidansteele/osx-abi-macho-file-format-reference>
- <https://www.smileykeith.com/2022/02/23/lc-linker-option/>
- https://github.com/apple/swift/blob/d6f9401c28b7588b98b72bcf36bfcdac420e2425/lib/IRGen/IRGenModule.cpp#L1641-L1806

ELF binaries linking with LLVM's lld can use the [`.linker-options` section](https://llvm.org/docs/Extensions.html#linker-options-section-linker-options) or the [`.deplibs` section](https://llvm.org/docs/Extensions.html#sht-llvm-dependent-libraries-section-dependent-libraries). LLVM also has the [`llvm.linker.options` named metadata](https://llvm.org/docs/LangRef.html#automatic-linker-flags-named-metadata).

Additional complication: `ld64` will not pick these up from archive members unless it's already loading the archive member, see also https://github.com/rust-lang/rust/pull/133832. Since `rustc` uses a lot of codegen units, and as such the specific codegen unit -> object file / archive member that contains the linker options might not be loaded by the linker.

As you can see, this is unfortunately quite platform-specific, and depends on the capabilities of the linker, so it probably isn't solvable in the general case; but I'd argue that this is still something that we could slowly improve support for, since this has a clear graceful fallback.

I'd be willing to (attempt to) implement this if you think this is desired?


## Drawbacks / Unknowns

More complex linking integration, would this work for "Rust lib depending on Rust static lib" use-case, if that's even possible today?

Linker arguments are inherently ordered, and may be unexpectedly jumbled by this transformation? Would have to be properly researched and tested.

Sometimes, the user may want to opt-out of this behaviour. This can be done with the linker flag `-ignore_auto_link`, though we should probably document that somewhere once this has been implemented.