Home • Explore • Blog • CI
☰



nixpkgs
5th chunk of `doc/stdenv/platform-notes.chapter.md`
c5f6d95e9c045563df76dd163b62b3c2f3e77a8cedcd60fa0000000100000936
When you propagate an SDK, it becomes part of your derivation’s public API, and changing the SDK or removing it can be a breaking change.
That is why propagating it is only recommended for compilers.

When authoring a compiler derivation, propagate the SDK only for the ways you expect users to use your compiler.
Depending on your expected use cases, you may have to do one or all of these.

- Put it in `depsTargetTargetPropagated` when your compiler is expected to be added to `nativeBuildInputs`.
  That will ensure the SDK is effectively part of the target derivation’s `buildInputs`.
- If your compiler uses a hook, put it in the hook’s `depsTargetTargetPropagated` instead.
  The effect should be the same as the above.
- If your package uses the builder pattern, update your builder to add the SDK to the derivation’s `buildInputs`.

If you’re not sure whether to propagate an SDK, don’t.
If your package is a compiler or language, and you’re not sure, ask @NixOS/darwin-maintainers for help deciding.

### Dealing with `darwin.apple_sdk.frameworks` {#sec-darwin-legacy-frameworks}

You may see references to `darwin.apple_sdk.frameworks`.
This is the legacy SDK pattern, and it is being phased out.
All packages in `darwin.apple_sdk`, `darwin.apple_sdk_11_0`, and `darwin.apple_sdk_12_3` are stubs that do nothing.
If your derivation references them, you can delete them. The default SDK should be enough to build your package.

Note: the new SDK pattern uses the name `apple-sdk` to better align with Nixpkgs naming conventions.
The legacy SDK pattern uses `apple_sdk`.
You always know you are using the old SDK pattern if the name is `apple_sdk`.

Some derivations may depend on the location of frameworks in those old packages.
To update your derivation to find them in the new SDK, use `$SDKROOT` instead in `preConfigure`.
For example, if you substitute `${darwin.apple_sdk.frameworks.OpenGL}/Library/Frameworks/OpenGL.framework` in `postPatch`, replace it with `$SDKROOT/System/Library/Frameworks/OpenGL.framework` in `preConfigure`.

Note that if your derivation is changing a system path (such as `/System/Library/Frameworks/OpenGL.framework`), you may be able to remove the path.
Compilers and binutils targeting Darwin look for system paths in the SDK sysroot.
Some of them (such as Zig or `bindgen` for Rust) depend on it.
Title: Darwin SDK Propagation and Legacy Frameworks
Summary
This section explains why propagating an SDK should primarily be done by compilers, as it becomes part of the derivation's public API. It provides guidance on adding the SDK to `depsTargetTargetPropagated` or a compiler hook, or updating the builder pattern to include it in the derivation's `buildInputs`. It also discusses the phasing out of the legacy SDK pattern (`darwin.apple_sdk.frameworks`) and advises users to delete references to these packages. The section provides instructions on how to update derivations to find frameworks in the new SDK using `$SDKROOT` in `preConfigure`.