Merge master into staging-next

4 files changed, 40 insertions, 25 deletions

diff --git a/doc/builders/packages/dlib.section.md b/doc/builders/packages/dlib.section.md
new file mode 100644
index 00000000000..8f0aa861018
--- /dev/null
+++ b/doc/builders/packages/dlib.section.md
@@ -0,0 +1,13 @@
+# DLib {#dlib}
+
+[DLib](http://dlib.net/) is a modern, C++-based toolkit which provides several machine learning algorithms.
+
+## Compiling without AVX support {#compiling-without-avx-support}
+
+Especially older CPUs don\'t support [AVX](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) (Advanced Vector Extensions) instructions that are used by DLib to optimize their algorithms.
+
+On the affected hardware errors like `Illegal instruction` will occur. In those cases AVX support needs to be disabled:
+
+```nix
+self: super: { dlib = super.dlib.override { avxSupport = false; }; }
+```
diff --git a/doc/builders/packages/dlib.xml b/doc/builders/packages/dlib.xml
deleted file mode 100644
index 5f768dd51b6..00000000000
--- a/doc/builders/packages/dlib.xml
+++ /dev/null
@@ -1,24 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="dlib">
- <title>DLib</title>
-
- <para>
-  <link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which provides several machine learning algorithms.
- </para>
-
- <section xml:id="compiling-without-avx-support">
-  <title>Compiling without AVX support</title>
-
-  <para>
-   Especially older CPUs don't support <link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link> (<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to optimize their algorithms.
-  </para>
-
-  <para>
-   On the affected hardware errors like <literal>Illegal instruction</literal> will occur. In those cases AVX support needs to be disabled:
-<programlisting>self: super: {
-  dlib = super.dlib.override { avxSupport = false; };
-}</programlisting>
-  </para>
- </section>
-</section>
diff --git a/doc/builders/packages/fuse.section.md b/doc/builders/packages/fuse.section.md
index 5603481115e..eb0023fcbc3 100644
--- a/doc/builders/packages/fuse.section.md
+++ b/doc/builders/packages/fuse.section.md
@@ -17,3 +17,29 @@ following, it's a likely sign that you need to have macFUSE installed.
     Referenced from: /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
     Reason: image not found
     [1]    92299 abort      /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
+
+Package maintainers may often encounter the following error when building FUSE
+packages on macOS:
+
+    checking for fuse.h... no
+    configure: error: No fuse.h found.
+
+This happens on autoconf based projects that uses `AC_CHECK_HEADERS` or
+`AC_CHECK_LIBS` to detect libfuse, and will occur even when the `fuse` package
+is included in `buildInputs`. It happens because libfuse headers throw an error
+on macOS if the `FUSE_USE_VERSION` macro is undefined. Many proejcts do define
+`FUSE_USE_VERSION`, but only inside C source files. This results in the above
+error at configure time because the configure script would attempt to compile
+sample FUSE programs without defining `FUSE_USE_VERSION`.
+
+There are two possible solutions for this problem in Nixpkgs:
+
+1. Pass `FUSE_USE_VERSION` to the configure script by adding
+   `CFLAGS=-DFUSE_USE_VERSION=25` in `configureFlags`. The actual value would
+   have to match the definition used in the upstream source code.
+2. Remove `AC_CHECK_HEADERS` / `AC_CHECK_LIBS` for libfuse.
+
+However, a better solution might be to fix the build script upstream to use
+`PKG_CHECK_MODULES` instead. This approach wouldn't suffer from the problem that
+`AC_CHECK_HEADERS`/`AC_CHECK_LIBS` has at the price of introducing a dependency
+on pkg-config.
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index a2bcd431531..f5b05b0bbcc 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -6,7 +6,7 @@
   This chapter contains information about how to use and maintain the Nix expressions for a number of specific packages, such as the Linux kernel or X.org.
  </para>
  <xi:include href="citrix.section.xml" />
- <xi:include href="dlib.xml" />
+ <xi:include href="dlib.section.xml" />
  <xi:include href="eclipse.section.xml" />
  <xi:include href="elm.section.xml" />
  <xi:include href="emacs.section.xml" />