doc/stdenv/platform-notes.chapter.md

   1 # Platform Notes {#chap-platform-notes}
   2
   3 ## Darwin (macOS) {#sec-darwin}
   4
   5 Some common issues when packaging software for Darwin:
   6
   7 - 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.
   8
   9   ```nix
  10   stdenv.mkDerivation {
  11     name = "libfoo-1.2.3";
  12     # ...
  13     buildPhase = ''
  14       $CC -o hello hello.c
  15     '';
  16   }
  17   ```
  18
  19 - 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`.
  20
  21   ```nix
  22   stdenv.mkDerivation {
  23     name = "libfoo-1.2.3";
  24     # ...
  25     makeFlags = lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
  26   }
  27   ```
  28
  29 - 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.
  30
  31   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.
  32
  33   ```
  34   dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib
  35   Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq
  36   Reason: image not found
  37   ./tests/jqtest: line 5: 75779 Abort trap: 6
  38   ```
  39
  40   ```nix
  41   stdenv.mkDerivation {
  42     name = "libfoo-1.2.3";
  43     # ...
  44     doInstallCheck = true;
  45     installCheckTarget = "check";
  46   }
  47   ```
  48
  49 - Some packages assume xcode is available and use `xcrun` to resolve build tools like `clang`, etc. This causes errors like `xcode-select: error: no developer tools were found at '/Applications/Xcode.app'` while the build doesn’t actually depend on xcode.
  50
  51   ```nix
  52   stdenv.mkDerivation {
  53     name = "libfoo-1.2.3";
  54     # ...
  55     prePatch = ''
  56       substituteInPlace Makefile \
  57           --replace-fail '/usr/bin/xcrun clang' clang
  58     '';
  59   }
  60   ```
  61
  62   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.
  63
  64 - x86_64-darwin uses the 10.12 SDK by default, but some software is not compatible with that version of the SDK. In that case,
  65   the 11.0 SDK used by aarch64-darwin is available for use on x86_64-darwin. To use it, reference `apple_sdk_11_0` instead of
  66   `apple_sdk` in your derivation and use `pkgs.darwin.apple_sdk_11_0.callPackage` instead of `pkgs.callPackage`. On Linux, this will
  67   have the same effect as `pkgs.callPackage`, so you can use `pkgs.darwin.apple_sdk_11_0.callPackage` regardless of platform.