mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-25 00:12:56 +00:00
doc: revise Darwin SDK documentation
Based on experience with other maintainers trying to update their packages, the documentation has been updated for clarity. It is also no longer recommended to propagate an SDK in most circumstances.
This commit is contained in:
Randy Eckenrode
parent
79def3b601
commit
b8b4cdc903
@ -2,242 +2,301 @@
|
||||
|
||||
## Darwin (macOS) {#sec-darwin}
|
||||
|
||||
Some common issues when packaging software for Darwin:
|
||||
The Darwin `stdenv` differs from most other ones in Nixpkgs in a few key ways.
|
||||
These differences reflect the default assumptions for building software on that platform.
|
||||
In many cases, you can ignore these differences because the software you are packaging is already written with them in mind.
|
||||
When you do that, write your derivation as normal. You don’t have to include any Darwin-specific special cases.
|
||||
The easiest way to know whether your derivation requires special handling for Darwin is to write it as if it doesn’t and see if it works.
|
||||
If it does, you’re done; skip the rest of this.
|
||||
|
||||
- The Darwin `stdenv` uses clang instead of gcc. When referring to the compiler `$CC` or `cc` will work in both cases. Some builds hardcode gcc/g++ in their build scripts, that can usually be fixed with using something like `makeFlags = [ "CC=cc" ];` or by patching the build scripts.
|
||||
- Darwin uses Clang by default instead of GCC. Packages that refer to `$CC` or `cc` should just work in most cases.
|
||||
Some packages may hardcode `gcc` or `g++`. You can usually fix that by setting `makeFlags = [ "CC=cc" "CXX=C++" ]`.
|
||||
If that does not work, you will have to patch the build scripts yourself to use the correct compiler for Darwin.
|
||||
- Darwin needs an SDK to build software.
|
||||
The SDK provides a default set of frameworks and libraries to build software, most of which are specific to Darwin.
|
||||
There are multiple versions of the SDK packages in Nixpkgs, but one is included by default in the `stdenv`.
|
||||
Usually, you don’t have to change or pick a different SDK. When in doubt, use the default.
|
||||
- The SDK used by your build can be found using the `DEVELOPER_DIR` environment variable.
|
||||
There are also versions of this variable available when cross-compiling depending on the SDK’s role.
|
||||
The `SDKROOT` variable is also set with the path to the SDK’s libraries and frameworks.
|
||||
`SDKROOT` is always a sub-folder of `DEVELOPER_DIR`.
|
||||
- Darwin includes a platform-specific tool called `xcrun` to help builds locate binaries they need.
|
||||
A version of `xcrun` is part of the `stdenv` on Darwin.
|
||||
If your package invokes `xcrun` via an absolute path (such as `/usr/bin/xcrun`), you will need to patch the build scripts to use `xcrun` instead.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
buildPhase = ''
|
||||
$CC -o hello hello.c
|
||||
'';
|
||||
}
|
||||
```
|
||||
To reiterate: you usually don’t have to worry about this stuff.
|
||||
Start with writing your derivation as if everything is already set up for you (because in most cases it already is).
|
||||
If you run into issues or failures, continue reading below for how to deal with the most common issues you may encounter.
|
||||
|
||||
- On Darwin, libraries are linked using absolute paths, libraries are resolved by their `install_name` at link time. Sometimes packages won’t set this correctly causing the library lookups to fail at runtime. This can be fixed by adding extra linker flags or by running `install_name_tool -id` during the `fixupPhase`.
|
||||
### Darwin Issue Troubleshooting {#sec-darwin-troubleshooting}
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
makeFlags = lib.optional stdenv.hostPlatform.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
|
||||
}
|
||||
```
|
||||
#### Package requires a non-default SDK or fails to build due to missing frameworks or symbols {#sec-darwin-troubleshooting-using-sdks}
|
||||
|
||||
- Even if the libraries are linked using absolute paths and resolved via their `install_name` correctly, tests can sometimes fail to run binaries. This happens because the `checkPhase` runs before the libraries are installed.
|
||||
In some cases, you may have to use a non-default SDK.
|
||||
This can happen when a package requires APIs that are not present in the default SDK.
|
||||
For example, Metal Performance Shaders were added in macOS 12.
|
||||
If the default SDK is 11.3, then a package that requires Metal Performance Shaders will fail to build due to missing frameworks and symbols.
|
||||
|
||||
This can usually be solved by running the tests after the `installPhase` or alternatively by using `DYLD_LIBRARY_PATH`. More information about this variable can be found in the *dyld(1)* manpage.
|
||||
To use a non-default SDK, add it to your derivation’s `buildInputs`.
|
||||
It is not necessary to override the SDK in the `stdenv` nor is it necessary to override the SDK used by your dependencies.
|
||||
If your derivation needs a non-default SDK at build time (e.g., for a `depsBuildBuild` compiler), see the cross-compilation documentation for which input you should use.
|
||||
|
||||
```
|
||||
dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib
|
||||
Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq
|
||||
Reason: image not found
|
||||
./tests/jqtest: line 5: 75779 Abort trap: 6
|
||||
```
|
||||
When determining whether to use a non-default SDK, consider the following:
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
doInstallCheck = true;
|
||||
installCheckTarget = "check";
|
||||
}
|
||||
```
|
||||
- Try building your derivation with the default SDK. If it works, you’re done.
|
||||
- If the package specifies a specific version, use that. See below for how to map Xcode version to SDK version.
|
||||
- If the package’s documentation indicates it supports optional features on newer SDKs, consider using the SDK that enables those features.
|
||||
If you’re not sure, use the default SDK.
|
||||
|
||||
- Some packages assume Xcode is available and use `xcrun` to resolve build tools like `clang`, etc. The Darwin stdenv includes `xcrun`, and it will return the path to any binary available in a build.
|
||||
Note: It is possible to have multiple, different SDK versions in your inputs.
|
||||
When that happens, the one with the highest version is always used.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
nativeBuildInputs = [ bison ];
|
||||
buildCommand = ''
|
||||
xcrun bison foo.y # produces foo.tab.c
|
||||
# ...
|
||||
'';
|
||||
}
|
||||
```
|
||||
The package `xcbuild` can be used to build projects that really depend on Xcode. However, this replacement is not 100% compatible with Xcode and can occasionally cause issues.
|
||||
|
||||
Note: Some packages may hardcode an absolute path to `xcrun`, `xcodebuild`, or `xcode-select`. Those paths should be removed or replaced.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
prePatch = ''
|
||||
substituteInPlace Makefile \
|
||||
--replace-fail /usr/bin/xcrun xcrun
|
||||
# or: --replace-fail /usr/bin/xcrun '${lib.getExe' buildPackages.xcbuild "xcrun"}'
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
- Multiple SDKs are available for use in nixpkgs. Each platform has a default SDK (10.12.2 for x86_64-darwin and 11.3 for aarch64-darwin), which is available as the `apple-sdk` package.
|
||||
|
||||
The SDK provides the necessary headers and text-based stubs to link common frameworks and libraries (such as libSystem, which is effectively Darwin’s libc). Projects will sometimes indicate which SDK to use by the Xcode version. As a rule of thumb, subtract one from the Xcode version to get the available SDK in nixpkgs.
|
||||
|
||||
The `DEVELOPER_DIR` variable in the build environment has the path to the SDK in the build environment. The `SDKROOT` variable there contains a sysroot with the framework, header, and library paths. You can reference an SDK’s sysroot from Nix using the `sdkroot` attribute on the SDK package. Note that it is preferable to use `SDKROOT` because the latter will be resolved to the highest SDK version of any available to your derivation.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
env.PACKAGE_SPECIFIC_SDK_VAR = apple-sdk_10_15.sdkroot;
|
||||
# or
|
||||
buildInputs = [ apple-sdk_10_15 ];
|
||||
postPatch = ''
|
||||
export PACKAGE_SPECIFIC_SDK_VAR=$SDKROOT
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
The following is a list of Xcode versions, the SDK version in nixpkgs, and the attribute to use to add it. Generally, only the last SDK release for a major version is packaged (each _x_ in 10._x_ until 10.15 is considered a major version).
|
||||
|
||||
| Xcode version | SDK version | nixpkgs attribute |
|
||||
|--------------------|---------------------------------------------------|-------------------|
|
||||
| Varies by platform | 10.12.2 (x86_64-darwin)<br/>11.3 (aarch64-darwin) | `apple-sdk` |
|
||||
| 8.0–8.3.3 | 10.12.2 | `apple-sdk_10_12` |
|
||||
| 9.0–9.4.1 | 10.13.2 | `apple-sdk_10_13` |
|
||||
| 10.0–10.3 | 10.14.6 | `apple-sdk_10_14` |
|
||||
| 11.0–11.7 | 10.15.6 | `apple-sdk_10_15` |
|
||||
| 12.0–12.5.1 | 11.3 | `apple-sdk_11` |
|
||||
| 13.0–13.4.1 | 12.3 | `apple-sdk_12` |
|
||||
| 14.0–14.3.1 | 13.3 | `apple-sdk_13` |
|
||||
| 15.0–15.4 | 14.4 | `apple-sdk_14` |
|
||||
| 16.0 | 15.0 | `apple-sdk_15` |
|
||||
|
||||
To use a non-default SDK, add it to your build inputs.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
buildInputs = [ apple-sdk_15 ]; # Uses the 15.0 SDK instead of the default SDK for the platform.
|
||||
}
|
||||
```
|
||||
|
||||
If your derivation has multiple SDKs its inputs (e.g., because they have been propagated by its dependencies), it will use the highest SDK version available.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3"; # Upstream specifies that it needs Xcode 12 to build, so use the 11.3 SDK.
|
||||
# ...
|
||||
buildInputs = [ apple-sdk_11 ];
|
||||
nativeBuildInputs = [ swift ]; # Propagates the 13.3 SDK, so the 13.3 SDK package will be used instead of the 11.3 SDK.
|
||||
}
|
||||
```
|
||||
|
||||
- When a package indicates a minimum supported version, also called the deployment target, you can set it in your derivation using `darwinMinVersionHook`. If you need to set a minimum version higher than the default SDK, you should also add the corresponding SDK to your `buildInputs`.
|
||||
|
||||
The deployment target controls how Darwin handles availability and access to some APIs. In most cases, if a deployment target is newer than the first availability of an API, that API will be linked directly. Otherwise, the API will be weakly linked and checked at runtime.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3"; # Upstream specifies the minimum supported version as 12.5.
|
||||
buildInputs = [ (darwinMinVersionHook "12.5") ];
|
||||
}
|
||||
```
|
||||
|
||||
If your derivation has multiple versions of this hook in its inputs (e.g., because it has been propagated by one of your dependencies), it will use the highest deployment target available.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3"; # Upstream specifies the minimum supported version as 10.15.
|
||||
buildInputs = [ qt6.qtbase (darwinMinVersionHook "10.15") ];
|
||||
}
|
||||
# Qt 6 specifies a minimum version of 12.0, so the minimum version resolves to 12.0.
|
||||
```
|
||||
|
||||
|
||||
- You should rely on the default SDK when possible. If a package specifies a required SDK version, use that version (e.g., libuv requires 11.0, so it should use `apple-sdk_11`). When a package supports multiple SDKs, determine which SDK package to use based on the following rules of thumb:
|
||||
|
||||
- If a package supports multiple SDK versions, use the lowest supported SDK version by the package (but no lower than the default SDK). That ensures maximal platform compatibility for the package.
|
||||
|
||||
- If a package specifies a range of supported SDK versions _and_ a minimum supported version, assume the package is using availability checks to support the indicated minimum version. Add the highest supported SDK and a `darwinMinVersionHook` set to the minimum version supported by the upstream package.
|
||||
|
||||
Warning: Avoid using newer SDKs than an upstream package supports. When a binary is linked on Darwin, the SDK version used to build it is recorded in the binary. Runtime behavior can vary based on the SDK version, which may work fine but can also result in unexpected behavior or crashes when building with an unsupported SDK.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "foo-1.2.3";
|
||||
# ...
|
||||
buildInputs = [ apple-sdk_15 (darwinMinVersionHook "10.15") ]; # Upstream builds with the 15.0 SDK but supports 10.15.
|
||||
}
|
||||
```
|
||||
|
||||
- Libraries that require a minimum version can propagate an appropriate SDK and `darwinMinVersionHook`. Derivations using that library will automatically use an appropriate SDK and minimum version. Even if the library builds with a newer SDK, it should propagate the minimum supported SDK. Derivations that need a newer SDK can add it to their `buildInputs`.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
buildInputs = [ apple-sdk_15 ]; # Upstream builds with the 15.0 SDK but supports 10.15.
|
||||
propagatedBuildInputs = [ apple-sdk_10_15 (darwinMinVersionHook "10.15") ];
|
||||
}
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
stdenv.mkDerivation {
|
||||
name = "bar-1.2.3";
|
||||
# ...
|
||||
buildInputs = [ libfoo ]; # Builds with the 10.15 SDK
|
||||
}
|
||||
buildInputs = [ apple-sdk_14 ];
|
||||
}
|
||||
```
|
||||
|
||||
#### What is a “deployment target” (or minimum version)? {#sec-darwin-troubleshooting-using-deployment-targets}
|
||||
|
||||
The “deployment target” refers to the minimum version of macOS that is expected to run an application.
|
||||
In most cases, the default is fine, and you don’t have to do anything else.
|
||||
If you’re not sure, don’t do anything, and that will probably be fine.
|
||||
|
||||
Some packages require setting a non-default deployment target (or minimum version) to gain access to certain APIs.
|
||||
You do that using the `darwinMinVersionHook`, which takes the deployment target version as a parameter.
|
||||
There are primarily two ways to determine the deployment target.
|
||||
|
||||
- The upstream documentation will specify a deployment target or minimum version. Use that.
|
||||
- The build will fail because an API requires a certain version. Use that.
|
||||
- In all other cases, you probably don’t need to specify a minimum version. The default is usually good enough.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3"; # Upstream specifies the minimum supported version as 12.5.
|
||||
buildInputs = [ (darwinMinVersionHook "12.5") ];
|
||||
}
|
||||
```
|
||||
|
||||
Note: It is possible to have multiple, different instances of `darwinMinVerisonHook` in your inputs.
|
||||
When that happens, the one with the highest version is always used.
|
||||
|
||||
#### Picking an SDK version {#sec-darwin-troubleshooting-picking-sdk-version}
|
||||
|
||||
The following is a list of Xcode versions, the SDK version in Nixpkgs, and the attribute to use to add it.
|
||||
Check your package’s documentation (platform support or installation instructions) to find which Xcode or SDK version to use.
|
||||
Generally, only the last SDK release for a major version is packaged (each _x_ in 10._x_ until 10.15 is considered a major version).
|
||||
|
||||
| Xcode version | SDK version | Nixpkgs attribute |
|
||||
|--------------------|---------------------------------------------------|-------------------|
|
||||
| Varies by platform | 10.12.2 (x86_64-darwin)<br/>11.3 (aarch64-darwin) | `apple-sdk` |
|
||||
| 8.0–8.3.3 | 10.12.2 | `apple-sdk_10_12` |
|
||||
| 9.0–9.4.1 | 10.13.2 | `apple-sdk_10_13` |
|
||||
| 10.0–10.3 | 10.14.6 | `apple-sdk_10_14` |
|
||||
| 11.0–11.7 | 10.15.6 | `apple-sdk_10_15` |
|
||||
| 12.0–12.5.1 | 11.3 | `apple-sdk_11` |
|
||||
| 13.0–13.4.1 | 12.3 | `apple-sdk_12` |
|
||||
| 14.0–14.3.1 | 13.3 | `apple-sdk_13` |
|
||||
| 15.0–15.4 | 14.4 | `apple-sdk_14` |
|
||||
| 16.0 | 15.0 | `apple-sdk_15` |
|
||||
|
||||
|
||||
#### Darwin Default SDK versions {#sec-darwin-troubleshooting-darwin-defaults}
|
||||
|
||||
The current default versions of the deployment target (minimum version) and SDK are indicated by Darwin-specific attributes on the platform. Because of the ways that minimum version and SDK can be changed that are not visible to Nix, they should be treated as lower bounds.
|
||||
If you need to parameterize over a specific version, create a function that takes the version as a parameter instead of relying on these attributes.
|
||||
|
||||
- `darwinMinVersion` defaults to 10.12 on x86_64-darwin and 11.0 on aarch64-darwin.
|
||||
It sets the default deployment target.
|
||||
- `darwinSdkVersion` defaults to 10.12 on x86-64-darwin and 11.0 on aarch64-darwin.
|
||||
Only the major version determines the SDK version, resulting in the 10.12.2 and 11.3 SDKs being used on these platforms respectively.
|
||||
|
||||
|
||||
#### `xcrun` cannot find a binary {#sec-darwin-troubleshooting-xcrun}
|
||||
|
||||
`xcrun` searches `PATH` and the SDK’s toolchain for binaries to run.
|
||||
If it cannot find a required binary, it will fail. When that happens, add the package for that binary to your derivation’s `nativeBuildInputs` (or `nativeCheckInputs` if the failure is happening when running tests).
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
stdenv.mkDerivation {
|
||||
name = "baz-1.2.3";
|
||||
nativeBuildInputs = [ bison ];
|
||||
buildCommand = ''
|
||||
xcrun bison foo.y # produces foo.tab.c
|
||||
# ...
|
||||
buildInputs = [ apple-sdk_12 libfoo ]; # Builds with the 12.3 SDK
|
||||
}
|
||||
```
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
- Many SDK libraries and frameworks use text-based stubs to link against system libraries and frameworks, but several are built from source (typically corresponding to the source releases for the latest release of macOS). Several of these are propagated to your package automatically. They can be accessed via the `darwin` package set along with others that are not propagated by default.
|
||||
#### Package requires `xcodebuild` {#sec-darwin-troubleshooting-xcodebuild}
|
||||
|
||||
- libiconv
|
||||
- libresolv
|
||||
- libsbuf
|
||||
The xcbuild package provides an `xcodebuild` command for packages that really depend on Xcode.
|
||||
This replacement is not 100% compatible and may run into some issues, but it is able to build many packages.
|
||||
To use `xcodebuild`, add `xcbuildHook` to your package’s `nativeBuildInputs`.
|
||||
It will provide a `buildPhase` for your derivation.
|
||||
You can use `xcbuildFlags` to specify flags to `xcodebuild` such as the required schema.
|
||||
If a schema has spaces in its name, you must set `__structuredAttrs` to `true`.
|
||||
See MoltenVK for an example of setting up xcbuild.
|
||||
|
||||
Other common libraries are available in Darwin-specific versions with modifications from Apple. Note that these packages may be made the default on Darwin in the future.
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
xcbuildFlags = [
|
||||
"-configuration"
|
||||
"Release"
|
||||
"-project"
|
||||
"libfoo-project.xcodeproj"
|
||||
"-scheme"
|
||||
"libfoo Package (macOS only)"
|
||||
];
|
||||
__structuredAttrs = true;
|
||||
}
|
||||
```
|
||||
|
||||
- ICU (compatible with the top-level icu package, but it also provides `libicucore.B.dylib` with an ABI compatible with the Darwin system version)
|
||||
- libpcap (compatible with the top-level libpcap, but it includes Darwin-specific extensions)
|
||||
##### Fixing absolute paths to `xcodebuild`, `xcrun`, and `PlistBuddy` {#sec-darwin-troubleshooting-xcodebuild-absolute-paths}
|
||||
|
||||
- The legacy SDKs packages are still available in the `darwin` package set under their existing names, but all packages in these SDKs (frameworks, libraries, etc) are stub packages for evaluation compatibility.
|
||||
Many build systems hardcode the absolute paths to `xcodebuild`, `xcrun`, and `PlistBuddy` as `/usr/bin/xcodebuild`, `/usr/bin/xcrun`, and `/usr/libexec/PlistBuddy` respectively.
|
||||
These paths will need to be replaced with relative paths and the xcbuild package if `xcodebuild` or `PListBuddy` are used.
|
||||
|
||||
In most cases, a derivation can be updated by deleting all of its SDK inputs (frameworks, libraries, etc). If you had to override the SDK, see below for how to do that using the new SDK pattern. If your derivation depends on the layout of the old frameworks or other internal details, you have more work to do.
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
postPatch = ''
|
||||
subsituteInPlace Makefile \
|
||||
--replace-fail '/usr/bin/xcodebuild' 'xcodebuild' \
|
||||
--replace-fail '/usr/bin/xcrun' 'xcrun' \
|
||||
--replace-fail '/usr/bin/PListBuddy' 'PListBuddy'
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
When a package depended on the location of frameworks, references to those framework packages can usually be replaced with `${apple-sdk.sdkroot}/System` or `$SDKROOT/System`. For example, if you substituted `${darwin.apple_sdk.frameworks.OpenGL}/Library/Frameworks/OpenGL.framework` in your derivation, you should replace it with `${apple-sdk.sdkroot}/System/Library/Frameworks/OpenGL.framework` or `$SDKROOT/System/Library/Frameworks`. The latter is preferred because it supports using the SDK that is resolved when multiple SDKs are propagated (see above).
|
||||
#### How to use libiconv on Darwin {#sec-darwin-troubleshooting-libiconv}
|
||||
|
||||
Note: the new SDK pattern uses the name `apple-sdk` to better align with nixpkgs naming conventions. The old SDK pattern uses `apple_sdk`.
|
||||
The libiconv package is included in the SDK by default along with libresolv and libsbuf.
|
||||
You do not need to do anything to use these packages. They are available automatically.
|
||||
If your derivation needs the `iconv` binary, add the `libiconv` package to your `nativeBuildInputs` (or `nativeCheckInputs` for tests).
|
||||
|
||||
- There are two legacy patterns that are being phased out. These patterns were used in the past to change the SDK version. They have been reimplemented to use the `apple-sdk` packages.
|
||||
#### Library install name issues {#sec-darwin-troubleshooting-install-name}
|
||||
|
||||
- `pkgs.darwin.apple_sdk_11_0.callPackage` - this pattern was used to provide frameworks from the 11.0 SDK. It now adds the `apple-sdk_11` package to your derivation’s build inputs.
|
||||
- `overrideSDK` - this stdenv adapter would try to replace the frameworks used by your derivation and its transitive dependencies. It now adds the `apple-sdk_11` package for `11.0` or the `apple-sdk_12` package for `12.3`. If `darwinMinVersion` is specified, it will add `darwinMinVersionHook` with the specified minimum version. No other SDK versions are supported.
|
||||
Libraries on Darwin are usually linked with absolute paths.
|
||||
This is determined by something called an “install name”, which is resolved at link time.
|
||||
Sometimes packages will not set this correctly, causing binaries linking to it not to find their libraries at runtime.
|
||||
This can be fixed by adding extra linker flags or by using `install_name_tool` to set it in `fixupPhase`.
|
||||
|
||||
- Darwin supports cross-compilation between Darwin platforms. Cross-compilation from Linux is not currently supported but may be supported in the future. To cross-compile to Darwin, you can set `crossSystem` or use one of the Darwin systems in `pkgsCross`. The `darwinMinVersionHook` and the SDKs support cross-compilation. If you need to specify a different SDK version for a `depsBuildBuild` compiler, add it to your `nativeBuildInputs`.
|
||||
##### Setting the install name via linker flags {#sec-darwin-troubleshooting-install-name-linker-flags}
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
depsBuildBuild = [ buildPackages.stdenv.cc ];
|
||||
nativeBuildInputs = [ apple-sdk_12 ];
|
||||
buildInputs = [ apple-sdk_13 ];
|
||||
depsTargetTargetPropagated = [ apple-sdk_14 ];
|
||||
}
|
||||
# The build-build clang will use the 12.3 SDK while the package build itself will use the 13.3 SDK.
|
||||
# Derivations that add this package as an input will have the 14.4 SDK propagated to them.
|
||||
```
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
makeFlags = lib.optional stdenv.hostPlatform.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
|
||||
}
|
||||
```
|
||||
|
||||
The different target SDK and hooks are mangled based on role:
|
||||
##### Setting the install name using `install_name_tool` {#sec-darwin-troubleshooting-install-name-install_name_tool}
|
||||
|
||||
- `DEVELOPER_DIR_FOR_BUILD` and `MACOSX_DEPLOYMENT_TARGET_FOR_BUILD` for the build platform;
|
||||
- `DEVELOPER_DIR` and `MACOSX_DEPLOYMENT_TARGET` for the host platform; and
|
||||
- `DEVELOPER_DIR_FOR_TARGET` and `MACOSX_DEPLOYMENT_TARGET_FOR_TARGET` for the build platform.
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
postFixup = ''
|
||||
# `-id <install_name>` takes the install name. The last parameter is the path to the library.
|
||||
${stdenv.cc.targetPrefix}install_name_tool -id "$out/lib/libfoo.dylib" "$out/lib/libfoo.dylib"
|
||||
'';
|
||||
}
|
||||
```
|
||||
|
||||
In static compilation situations, it is possible for the build and host platform to be the same platform but have different SDKs with the same version (one dynamic and one static). cc-wrapper takes care of handling this distinction.
|
||||
Even if libraries are linked using absolute paths and resolved via their install name correctly, tests in `checkPhase` can sometimes fail to run binaries because they are linked against libraries that have not yet been installed.
|
||||
This can usually be solved by running the tests after the `installPhase` or by using `DYLD_LIBRARY_PATH` (see {manpage}`dyld(1)` for more on setting `DYLD_LIBRARY_PATH`).
|
||||
|
||||
- The current default versions of the deployment target (minimum version) and SDK are indicated by Darwin-specific attributes on the platform. Because of the ways that minimum version and SDK can be changed that are not visible to Nix, they should be treated as lower bounds. If you need to parameterize over a specific version, create a function that takes the version as a parameter instead of relying on these attributes.
|
||||
##### Setting the install name using `fixDarwinDylibNames` hook {#sec-darwin-troubleshooting-install-name-fixDarwinDylibNames}
|
||||
|
||||
- `darwinMinVersion` defaults to 10.12 on x86_64-darwin and 11.0 on aarch64-darwin. It sets the default `MACOSX_DEPLOYMENT_TARGET`.
|
||||
- `darwinSdkVersion` defaults to 10.12 on x86-64-darwin and 11.0 on aarch64-darwin. Only the major version determines the SDK version, resulting in the 10.12.2 and 11.3 SDKs being used on these platforms respectively.
|
||||
If your package has numerous dylibs needing fixed, while it is preferable to fix the issue in the package’s build, you can update them all by adding the `fixDarwinDylibNames` hook to your `nativeBuildInputs`.
|
||||
This hook will scan your package’s outputs for dylibs and correct their install names.
|
||||
Note that if any binaries in your outputs linked those dylibs, you may need to use `install_name_tool` to replace references to them with the correct paths.
|
||||
|
||||
#### Propagating an SDK (advanced, compilers-only) {#sec-darwin-troubleshooting-propagating-sdks}
|
||||
|
||||
The SDK is a package, and it can be propagated.
|
||||
`darwinMinVersionHook` with a version specified can also be propagated.
|
||||
However, most packages should *not* do this.
|
||||
The exception is compilers.
|
||||
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.
|
||||
|
||||
#### Updating legacy SDK overrides {#sec-darwin-legacy-frameworks-overrides}
|
||||
|
||||
The legacy SDK provided two ways of overriding the default SDK.
|
||||
These are both being phased out along with the legacy SDKs.
|
||||
They have been updated to set up the new SDK for you, but you should replace them with doing that directly.
|
||||
|
||||
- `pkgs.darwin.apple_sdk_11_0.callPackage` - this pattern was used to provide frameworks from the 11.0 SDK.
|
||||
It now adds the `apple-sdk_11` package to your derivation’s build inputs.
|
||||
- `overrideSDK` - this stdenv adapter would try to replace the frameworks used by your derivation and its transitive dependencies.
|
||||
It now adds the `apple-sdk_11` package for `11.0` or the `apple-sdk_12` package for `12.3`.
|
||||
If `darwinMinVersion` is specified, it will add `darwinMinVersionHook` with the specified minimum version.
|
||||
No other SDK versions are supported.
|
||||
|
||||
### Darwin Cross-Compilation {#sec-darwin-legacy-cross-compilation}
|
||||
|
||||
Darwin supports cross-compilation between Darwin platforms.
|
||||
Cross-compilation from Linux is not currently supported but may be supported in the future.
|
||||
To cross-compile to Darwin, you can set `crossSystem` or use one of the Darwin systems in `pkgsCross`.
|
||||
The `darwinMinVersionHook` and the SDKs support cross-compilation.
|
||||
If you need to specify a different SDK version for a `depsBuildBuild` compiler, add it to your `nativeBuildInputs`.
|
||||
|
||||
```nix
|
||||
stdenv.mkDerivation {
|
||||
name = "libfoo-1.2.3";
|
||||
# ...
|
||||
depsBuildBuild = [ buildPackages.stdenv.cc ];
|
||||
nativeBuildInputs = [ apple-sdk_12 ];
|
||||
buildInputs = [ apple-sdk_13 ];
|
||||
depsTargetTargetPropagated = [ apple-sdk_14 ];
|
||||
}
|
||||
# The build-build `clang` will use the 12.3 SDK while the package build itself will use the 13.3 SDK.
|
||||
# Derivations that add this package as an input will have the 14.4 SDK propagated to them.
|
||||
```
|
||||
|
||||
The different target SDK and hooks are mangled based on role:
|
||||
|
||||
- `DEVELOPER_DIR_FOR_BUILD` and `MACOSX_DEPLOYMENT_TARGET_FOR_BUILD` for the build platform;
|
||||
- `DEVELOPER_DIR` and `MACOSX_DEPLOYMENT_TARGET` for the host platform; and
|
||||
- `DEVELOPER_DIR_FOR_TARGET` and `MACOSX_DEPLOYMENT_TARGET_FOR_TARGET` for the build platform.
|
||||
|
||||
In static compilation situations, it is possible for the build and host platform to be the same platform but have different SDKs with the same version (one dynamic and one static).
|
||||
cc-wrapper and bintools-wrapper take care of handling this distinction.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user