diff options
author | Orivej Desh <orivej@gmx.fr> | 2017-11-05 18:04:21 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-11-05 18:04:21 +0000 |
commit | 48cacf5ff7fc722b063a23c3843d87727741f21b (patch) | |
tree | d4f2c0d639087696dc971003416556b60480b361 /doc | |
parent | eddbd38611eeb0045d6d9467487cff370e4b2978 (diff) | |
parent | 633b03c57f658d57a192eabb088b171b4542081e (diff) |
Merge pull request #30951 from LnL7/darwin-docs
docs: add section on common darwin issues
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manual.xml | 1 | ||||
-rw-r--r-- | doc/platform-notes.xml | 83 |
2 files changed, 84 insertions, 0 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/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> |