path: root/doc/platform-notes.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-platform-nodes">
 <title>Platform Notes</title>
 <section xml:id="sec-darwin">
  <title>Darwin (macOS)</title>

  <para>
   Some common issues when packaging software for Darwin:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     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.
    </para>
<programlisting>
      stdenv.mkDerivation {
        name = "libfoo-1.2.3";
        # ...
        buildPhase = ''
          $CC -o hello hello.c
        '';
      }
    </programlisting>
   </listitem>
   <listitem>
    <para>
     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>.
    </para>
<programlisting>
      stdenv.mkDerivation {
        name = "libfoo-1.2.3";
        # ...
        makeFlags = stdenv.lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
      }
    </programlisting>
   </listitem>
   <listitem>
    <para>
     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.
    </para>
    <para>
     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>
     <refentrytitle>dyld</refentrytitle>
     <manvolnum>1</manvolnum></citerefentry> manpage.
    </para>
<programlisting>
      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
    </programlisting>
<programlisting>
      stdenv.mkDerivation {
        name = "libfoo-1.2.3";
        # ...
        doInstallCheck = true;
        installCheckTarget = "check";
      }
    </programlisting>
   </listitem>
   <listitem>
    <para>
     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.
    </para>
<programlisting>
      stdenv.mkDerivation {
        name = "libfoo-1.2.3";
        # ...
        prePatch = ''
          substituteInPlace Makefile \
              --replace '/usr/bin/xcrun clang' clang
        '';
      }
    </programlisting>
    <para>
     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.
    </para>
   </listitem>
  </itemizedlist>
 </section>
</chapter>