@@ -137,4 +137,118 @@ self: super:
137137 Overlays are similar to other methods for customizing Nixpkgs, in particular the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>. Indeed, <literal>packageOverrides</literal> acts as an overlay with only the <varname>super</varname> argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute.
138138 </para>
139139 </section>
140+ <section xml:id="sec-overlays-alternatives">
141+ <title>Using overlays to configure alternatives</title>
142+ <para>
143+ Certain software has different implementations of the same
144+ interface. Other distributions have functionality to switch
145+ between these. For example, Debian provides <link
146+ xlink:href="https://wiki.debian.org/DebianAlternatives">DebianAlternatives</link>.
147+ Nixpkgs has what we call <literal>alternatives</literal>, which
148+ are configured through overlays.
149+ </para>
150+ <section xml:id="sec-overlays-alternatives-blas-lapack">
151+ <title>BLAS/LAPACK</title>
152+ <para>
153+ In Nixpkgs, we have multiple implementations of the BLAS/LAPACK
154+ numerical linear algebra interfaces. They are:
155+ </para>
156+ <itemizedlist>
157+ <listitem>
158+ <para>
159+ <link xlink:href="https://www.openblas.net/">OpenBLAS</link>
160+ </para>
161+ <para>
162+ The Nixpkgs attribute is <literal>openblas</literal> for
163+ ILP64 and <literal>openblasCompat</literal> for LP64. This
164+ is the default.
165+ </para>
166+ </listitem>
167+ <listitem>
168+ <para>
169+ <link xlink:href="http://www.netlib.org/lapack/">LAPACK
170+ reference</link> (also provides BLAS)
171+ </para>
172+ <para>
173+ The Nixpkgs attribute is <literal>lapack-reference</literal>.
174+ </para>
175+ </listitem>
176+ <listitem>
177+ <para>
178+ <link
179+ xlink:href="https://software.intel.com/en-us/mkl">Intel
180+ MKL</link> (only works on x86 architecture, unfree)
181+ </para>
182+ <para>
183+ The Nixpkgs attribute is <literal>mkl</literal>.
184+ </para>
185+ </listitem>
186+ </itemizedlist>
187+ <para>
188+ Introduced in <link
189+ xlink:href="https://github.com/NixOS/nixpkgs/pull/83888">PR
190+ #83888</link>, we are able to override the ‘blas’ and ‘lapack’
191+ packages to use different implementations, through the
192+ ‘blasProvider’ and ‘lapackProvider’ argument. This can be used
193+ to select a different provider. For example, an overlay can be
194+ created that looks like:
195+ </para>
196+ <programlisting>
197+self: super:
198+
199+{
200+ blas = super.blas.override {
201+ blasProvider = self.mkl;
202+ }
203+ lapack = super.lapack.override {
204+ lapackProvider = self.mkl;
205+ }
206+}
207+ </programlisting>
208+ <para>
209+ This overlay uses Intel’s MKL library for both BLAS and LAPACK
210+ interfaces. Note that the same can be accomplished at runtime
211+ using <literal>LD_PRELOAD</literal> of libblas.so.3 and
212+ liblapack.so.3.
213+ </para>
214+ <para>
215+ Intel MKL requires an <literal>openmp</literal> implementation
216+ when running with multiple processors. By default,
217+ <literal>mkl</literal> will use Intel’s <literal>iomp</literal>
218+ implementation if no other is specified, but this is a
219+ runtime-only dependency and binary compatible with the LLVM
220+ implementation. To use that one instead, Intel recommends users
221+ set it with <literal>LD_PRELOAD</literal>. Note that
222+ <literal>mkl</literal> is only available on
223+ <literal>x86_64-linux</literal> and
224+ <literal>x86_64-darwin</literal>. Moreover, Hydra is not build
225+ and distributing pre-compiled binaries using it.
226+ </para>
227+ <para>
228+ For BLAS/LAPACK switching to work correctly, all packages must
229+ depend on <literal>blas</literal> or <literal>lapack</literal>.
230+ This ensures that only one BLAS/LAPACK library is used at one
231+ time. There are two versions versions of BLAS/LAPACK currently
232+ in the wild, <literal>LP64</literal> (integer size = 32 bits)
233+ and <literal>ILP64</literal> (integer size = 64 bits). Some
234+ software needs special flags or patches to work with
235+ <literal>ILP64</literal>. You can check if
236+ <literal>ILP64</literal> is used in Nixpkgs with
237+ <varname>blas.isILP64</varname> and
238+ <varname>lapack.isILP64</varname>. Some software does NOT work
239+ with <literal>ILP64</literal>, and derivations need to specify
240+ an assertion to prevent this. You can prevent
241+ <literal>ILP64</literal> from being used with the following:
242+ </para>
243+ <programlisting>
244+{ stdenv, blas, lapack, ... }:
245+
246+assert (!blas.isILP64) && (!lapack.isILP64);
247+
248+stdenv.mkDerivation {
249+ ...
250+}
251+ </programlisting>
252+ </section>
253+ </section>
140254</chapter>