doc/stdenv/platform-notes: convert to markdown

3 files changed, 63 insertions, 84 deletions

diff --git a/doc/manual.xml b/doc/manual.xml
index 8cecb01fc22..b0490ec74ae 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -19,7 +19,7 @@
   <xi:include href="stdenv/meta.xml" />
   <xi:include href="stdenv/multiple-output.xml" />
   <xi:include href="stdenv/cross-compilation.chapter.xml" />
-  <xi:include href="stdenv/platform-notes.xml" />
+  <xi:include href="stdenv/platform-notes.chapter.xml" />
  </part>
  <part>
   <title>Builders</title>
diff --git a/doc/stdenv/platform-notes.chapter.md b/doc/stdenv/platform-notes.chapter.md
new file mode 100644
index 00000000000..03e61e333f8
--- /dev/null
+++ b/doc/stdenv/platform-notes.chapter.md
@@ -0,0 +1,62 @@
+# Platform Notes {#chap-platform-notes}
+
+## Darwin (macOS) {#sec-darwin}
+
+Some common issues when packaging software for Darwin:
+
+- The Darwin `stdenv` uses clang instead of gcc. When referring to the compiler `$CC` or `cc` will work in both cases. Some builds hardcode gcc/g++ in their build scripts, that can usually be fixed with using something like `makeFlags = [ "CC=cc" ];` or by patching the build scripts.
+
+  ```nix
+  stdenv.mkDerivation {
+    name = "libfoo-1.2.3";
+    # ...
+    buildPhase = ''
+      $CC -o hello hello.c
+    '';
+  }
+  ```
+
+- On Darwin, libraries are linked using absolute paths, libraries are resolved by their `install_name` 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 `install_name_tool -id` during the `fixupPhase`.
+
+  ```nix
+  stdenv.mkDerivation {
+    name = "libfoo-1.2.3";
+    # ...
+    makeFlags = lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
+  }
+  ```
+
+- Even if the libraries are linked using absolute paths and resolved via their `install_name` correctly, tests can sometimes fail to run binaries. This happens because the `checkPhase` runs before the libraries are installed.
+
+  This can usually be solved by running the tests after the `installPhase` or alternatively by using `DYLD_LIBRARY_PATH`. More information about this variable can be found in the *dyld(1)* manpage.
+
+  ```
+  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
+  ```
+
+  ```nix
+  stdenv.mkDerivation {
+    name = "libfoo-1.2.3";
+    # ...
+    doInstallCheck = true;
+    installCheckTarget = "check";
+  }
+  ```
+
+- Some packages assume xcode is available and use `xcrun` to resolve build tools like `clang`, etc. This causes errors like `xcode-select: error: no developer tools were found at '/Applications/Xcode.app'` while the build doesn’t actually depend on xcode.
+
+  ```nix
+  stdenv.mkDerivation {
+    name = "libfoo-1.2.3";
+    # ...
+    prePatch = ''
+      substituteInPlace Makefile \
+          --replace '/usr/bin/xcrun clang' clang
+    '';
+  }
+  ```
+
+  The package `xcbuild` 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.
diff --git a/doc/stdenv/platform-notes.xml b/doc/stdenv/platform-notes.xml
deleted file mode 100644
index cc8efaece12..00000000000
--- a/doc/stdenv/platform-notes.xml
+++ /dev/null
@@ -1,83 +0,0 @@
-<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 = 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>