diff options
Diffstat (limited to 'doc/stdenv/platform-notes.xml')
-rw-r--r-- | doc/stdenv/platform-notes.xml | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/doc/stdenv/platform-notes.xml b/doc/stdenv/platform-notes.xml new file mode 100644 index 0000000000000..5a266fdc0eea0 --- /dev/null +++ b/doc/stdenv/platform-notes.xml @@ -0,0 +1,83 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="chap-platform-notes"> + <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> |