doc/stdenv/platform-notes.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xml:id="chap-platform-notes">
   4  <title>Platform Notes</title>
   5  <section xml:id="sec-darwin">
   6   <title>Darwin (macOS)</title>
   7
   8   <para>
   9    Some common issues when packaging software for Darwin:
  10   </para>
  11
  12   <itemizedlist>
  13    <listitem>
  14     <para>
  15      The Darwin <literal>stdenv</literal> uses clang instead of gcc. When referring to the compiler <varname>$CC</varname> or <command>cc</command> will work in both cases. Some builds hardcode gcc/g++ in their build scripts, that can usually be fixed with using something like <literal>makeFlags = [ "CC=cc" ];</literal> or by patching the build scripts.
  16     </para>
  17 <programlisting>
  18 stdenv.mkDerivation {
  19   name = "libfoo-1.2.3";
  20   # ...
  21   buildPhase = ''
  22     $CC -o hello hello.c
  23   '';
  24 }
  25 </programlisting>
  26    </listitem>
  27    <listitem>
  28     <para>
  29      On Darwin, libraries are linked using absolute paths, libraries are resolved by their <literal>install_name</literal> 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 <command>install_name_tool -id</command> during the <function>fixupPhase</function>.
  30     </para>
  31 <programlisting>
  32 stdenv.mkDerivation {
  33   name = "libfoo-1.2.3";
  34   # ...
  35   makeFlags = stdenv.lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
  36 }
  37 </programlisting>
  38    </listitem>
  39    <listitem>
  40     <para>
  41      Even if the libraries are linked using absolute paths and resolved via their <literal>install_name</literal> correctly, tests can sometimes fail to run binaries. This happens because the <varname>checkPhase</varname> runs before the libraries are installed.
  42     </para>
  43     <para>
  44      This can usually be solved by running the tests after the <varname>installPhase</varname> or alternatively by using <varname>DYLD_LIBRARY_PATH</varname>. More information about this variable can be found in the <citerefentry>
  45      <refentrytitle>dyld</refentrytitle>
  46      <manvolnum>1</manvolnum></citerefentry> manpage.
  47     </para>
  48 <programlisting>
  49 dyld: Library not loaded: /nix/store/7hnmbscpayxzxrixrgxvvlifzlxdsdir-jq-1.5-lib/lib/libjq.1.dylib
  50 Referenced from: /private/tmp/nix-build-jq-1.5.drv-0/jq-1.5/tests/../jq
  51 Reason: image not found
  52 ./tests/jqtest: line 5: 75779 Abort trap: 6
  53 </programlisting>
  54 <programlisting>
  55 stdenv.mkDerivation {
  56   name = "libfoo-1.2.3";
  57   # ...
  58   doInstallCheck = true;
  59   installCheckTarget = "check";
  60 }
  61 </programlisting>
  62    </listitem>
  63    <listitem>
  64     <para>
  65      Some packages assume xcode is available and use <command>xcrun</command> to resolve build tools like <command>clang</command>, etc. This causes errors like <code>xcode-select: error: no developer tools were found at '/Applications/Xcode.app'</code> while the build doesn't actually depend on xcode.
  66     </para>
  67 <programlisting>
  68 stdenv.mkDerivation {
  69   name = "libfoo-1.2.3";
  70   # ...
  71   prePatch = ''
  72     substituteInPlace Makefile \
  73         --replace '/usr/bin/xcrun clang' clang
  74   '';
  75 }
  76 </programlisting>
  77     <para>
  78      The package <literal>xcbuild</literal> 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.
  79     </para>
  80    </listitem>
  81   </itemizedlist>
  82  </section>
  83 </chapter>