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>
      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 projects that build some kind of
      graphical interface won't work without using Xcode in an impure way.
    </para>
  </listitem>

</itemizedlist>
</section>

</chapter>