doc/overlays.xml: update documentation for BLAS/LAPACK

This expands the documentation and explains how to assert LP64.

doc/using/overlays.xml

@@ -177,7 +177,7 @@ self: super:
          <para>
            <link
            xlink:href="https://software.intel.com/en-us/mkl">Intel
-           MKL</link> (only works on x86 architecture)
+           MKL</link> (only works on x86 architecture, unfree)
          </para>
          <para>
            The Nixpkgs attribute is <literal>mkl</literal>.
@@ -211,6 +211,44 @@ self: super:
        using <literal>LD_PRELOAD</literal> of libblas.so.3 and
        liblapack.so.3.
      </para>
+     <para>
+       Intel MKL requires an <literal>openmp</literal> implementation
+       when running with multiple processors. By default,
+       <literal>mkl</literal> will use Intel’s <literal>iomp</literal>
+       implementation if no other is specified, but this is a
+       runtime-only dependency and binary compatible with the LLVM
+       implementation. To use that one instead, Intel recommends users
+       set it with <literal>LD_PRELOAD</literal>. Note that
+       <literal>mkl</literal> is only available on
+       <literal>x86_64-linux</literal> and
+       <literal>x86_64-darwin</literal>. Moreover, Hydra is not build
+       and distributing pre-compiled binaries using it.
+     </para>
+     <para>
+       For BLAS/LAPACK switching to work correctly, all packages must
+       depend on <literal>blas</literal> or <literal>lapack</literal>.
+       This ensures that only one BLAS/LAPACK library is used at one
+       time. There are two versions versions of BLAS/LAPACK currently
+       in the wild, <literal>LP64</literal> (integer size = 32 bits)
+       and <literal>ILP64</literal> (integer size = 64 bits). Some
+       software needs special flags or patches to work with
+       <literal>ILP64</literal>. You can check if
+       <literal>ILP64</literal> is used in Nixpkgs with
+       <varname>blas.isILP64</varname> and
+       <varname>lapack.isILP64</varname>. Some software does NOT work
+       with <literal>ILP64</literal>, and derivations need to specify
+       an assertion to prevent this. You can prevent
+       <literal>ILP64</literal> from being used with the following:
+     </para>
+     <programlisting>
+{ stdenv, blas, lapack, ... }:
+
+assert (!blas.isILP64) &amp;&amp; (!lapack.isILP64);
+
+stdenv.mkDerivation {
+  ...
+}
+     </programlisting>
    </section>
  </section>
 </chapter>