diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual.xml | 1 | ||||
| -rw-r--r-- | doc/meta.xml | 8 | ||||
| -rw-r--r-- | doc/platform-notes.xml | 83 |
3 files changed, 87 insertions, 5 deletions
diff --git a/doc/manual.xml b/doc/manual.xml index 75bd21557fd15..eb0a24789d44c 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -18,6 +18,7 @@ <xi:include href="functions.xml" /> <xi:include href="meta.xml" /> <xi:include href="languages-frameworks/index.xml" /> + <xi:include href="platform-notes.xml" /> <xi:include href="package-notes.xml" /> <xi:include href="overlays.xml" /> <xi:include href="coding-conventions.xml" /> diff --git a/doc/meta.xml b/doc/meta.xml index b1ffd0502b2b5..0f9dccfb91b58 100644 --- a/doc/meta.xml +++ b/doc/meta.xml @@ -200,11 +200,9 @@ meta-attributes</title> meta.platforms = stdenv.lib.platforms.linux; </programlisting> - Attribute Set <varname>stdenv.lib.platforms</varname> in - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/platforms.nix"> - <filename>nixpkgs/lib/platforms.nix</filename></link> defines various common - lists of platforms types. - </para></listitem> + Attribute Set <varname>stdenv.lib.platforms</varname> defines + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> + various common lists</link> of platforms types.</para></listitem> </varlistentry> <varlistentry> diff --git a/doc/platform-notes.xml b/doc/platform-notes.xml new file mode 100644 index 0000000000000..f4f6ec6002941 --- /dev/null +++ b/doc/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-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> |