Repository: rust
Issue: Apple deployment target, SDK root and SDK version
Labels: C-discussion,O-apple

I've been looking into our handling of the deployment targets and SDK paths on Apple platforms, and I've found it to be somewhat inconsistent and in some places outright incorrect. I'm opening this issue to give context to the PRs I've been (and will be) opening to fix it.


## Deployment targets

The "deployment target" is the minimum operating system version that the final binary will work on. It can be configured with the `*_DEPLOYMENT_TARGET` environment variables, and setting it allows us to enable certain optimizations. Currently this is done primarily in the codegen backend LLVM, though it could also be done by Cranelift or GCC if they wanted to, and also by `std` or other library crates.

By default, Clang takes the default deployment target from the SDK, which is usually quite high. `rustc` chooses a different approach here, and compiles by default for the minimum supported version, which I believe is the right choice, as it forces users to use the correct `*_DEPLOYMENT_TARGET` if they need to use newer features.

I've aligned the default/minimum versions of this variable with Clang in https://github.com/rust-lang/rust/pull/129367, and made sure we rebuild when the user changes it in https://github.com/rust-lang/rust/pull/129342.


## `SDKROOT`

The SDK root contains system header files and linker Text-Based stub files (`.tbd`). The SDK path is passed to the static linker (`ld`) so that it can tell which system library a given symbol comes from, and in turn write this information in the final Mach-O, so that it can be read by the dynamic linker (`dyld`) at runtime.

System libraries have been "hidden away" in the `dyld` cache since macOS 11 Big Sur, and since Rust does not distribute the linker stubs (unlike e.g. `zig cc` does on macOS), the SDK root is effectively always required to link anything (whether it's a cross-compile or not).

The correct way to invoke e.g. Clang, then, is using `xcrun` to pass the desired SDK in the `SDKROOT` environment variable, e.g.:
```console
$ xcrun --sdk iphoneos clang -target aarch64-apple-ios-macabi foo.c -o foo
```

This is not the full story, however: The binary at `/usr/bin/clang` is actually a trampoline that (effectively) invokes `xcrun` and then calls out to the actual `clang` binary distributed with Xcode, which means that a plain `clang foo.c` command usually works, at least when compiling for the host macOS. (In the case where you've compiled Clang from source instead, then this won't work, and you _have_ to provide the SDK root).

`rustc` is in a bit of a trickier position than Clang though:
- We're not a system built-in under `/usr/bin`, and as such don't get the affordances of automatically having `SDKROOT` set.
- The design of Cargo means that `rustc` will be invoked for different targets, but with the same `SDKROOT`. E.g. compiling build scripts when running Cargo under Xcode, `SDKROOT` will usually be set for an iOS SDK, while the build script will be targetting the host macOS.
- We try to make it easy to cross-compile by default, so we want to figure out the SDK root from the target instead of forcing the user to specify it.

Some of this already works (and kudos to the people that have implemented this in the past), but it's currently incomplete, which means we as a stop-gap end up shelling out to `xcrun` to let it figure out a SDK root for us. I believe that `rustc` should, when linking, re-implement the SDK discovery logic that `xcrun` does, see https://github.com/rust-lang/rust/pull/131433, and should always set the SDK root when invoking the linker, see https://github.com/rust-lang/rust/pull/131477.


## SDK version and `LC_BUILD_VERSION`

The SDK root is also used for something else in Clang: To find the SDK version, and embed it, together with the deployment target, in the `LC_BUILD_VERSION` of the produced (Mach-O) binary. It is quite important that this load command is present, otherwise the linker may refuse to link the binary (see https://github.com/rust-lang/rust/pull/114114 and https://github.com/rust-lang/rust/pull/111384), as it cannot reliably figure out the target OS and ABI.

The SDK version is used by `dyld` to emit more errors on newer binaries (see [here](https://github.com/apple-oss-distributions/dyld/blob/dyld-1165.3/common/MachOFile.cpp#L3029) and [here](https://github.com/apple-oss-distributions/dyld/blob/dyld-1165.3/common/MachOFile.cpp#L3738-L3857)), but also by system frameworks internally to change behaviour when compiled for an older SDK, for example [`-[NSView wantsBestResolutionOpenGLSurface]`](https://developer.apple.com/documentation/appkit/nsview/1414938-wantsbestresolutionopenglsurface?language=objc). I suspect the deployment target to be used to similar purposes.

https://github.com/rust-lang/rust/pull/129369 ensures that we consistently set the deployment target for all produced binaries.

The SDK version is set differently by `rustc` depending on what kind of binary is being produced:
- Raw object files: Delegate to the codegen backend (LLVM sets it to `0` or `n/a`).
- Other object files: Currently [a hard-coded value](https://github.com/rust-lang/rust/blob/5ad98b4026d5172f27615b105658bc8bfd677be8/compiler/rustc_target/src/spec/base/apple/mod.rs#L200-L213), but I've changed it to `0` in https://github.com/rust-lang/rust/pull/131016 to match LLVM.
- Everything linked with `cc`: Give Clang the SDK root, and let them figure it out.
- Everything linked with `ld`: Set to be equal to the deployment target. I think a better approach here would be to read the SDK version from the `SDKSettings.json`, to match what Clang does. I have implemented this in https://github.com/rust-lang/rust/pull/131478.


## Conclusion

Within the constraints that we have (Cargo is target agnostic, and won't deal with this, though it's better positioned to do so IMO), I think that the approach that `rustc` takes is a fairly good, and would be even better with a few fixes ;).

Just to clarify, in the end, `rustc`'s dependency on these variables (i.e. the effect on incremental compilation) would be roughly:
- `*_DEPLOYMENT_TARGET`: Codegen.
- `SDKROOT`/`DEVELOPER_DIR`/`/var/db/xcode_select_link`/...: Linking.

That is, ideally `cargo check` shouldn't be influenced by them at all, and `cargo build` only re-link the last binaries if the SDK root changed, and should recompile all binaries if the deployment target changed.

We will also need to ensure that the `cc` crate also handles all of this correctly too (see for example https://github.com/rust-lang/rust/issues/128419 for a current issue) (it's much more difficult there, since they have backwards compatibility issues).

---

@rustbot label O-apple

CC the Apple experts I know of:
@simlay, @BlackHoleFox, @thomcc, @shepmaster