diff --git a/doc/manual.xml b/doc/manual.xml
index 75bd21557fd1..eb0a24789d44 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 000000000000..f4f6ec600294
--- /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>