diff --git a/doc/using/overlays.xml b/doc/using/overlays.xml
index 26a888368ab..7732e0ac217 100644
--- a/doc/using/overlays.xml
+++ b/doc/using/overlays.xml
@@ -137,4 +137,80 @@ self: super:
Overlays are similar to other methods for customizing Nixpkgs, in particular the packageOverrides attribute described in . Indeed, packageOverrides acts as an overlay with only the super argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute.
+
+ Using overlays to configure alternatives
+
+ Certain software has different implementations of the same
+ interface. Other distributions have functionality to switch
+ between these. For example, Debian provides DebianAlternatives.
+ Nixpkgs has what we call alternatives, which
+ are configured through overlays.
+
+
+ BLAS/LAPACK
+
+ In Nixpkgs, we have multiple implementations of the BLAS/LAPACK
+ numerical linear algebra interfaces. They are:
+
+
+
+
+ OpenBLAS
+
+
+ The Nixpkgs attribute is openblas for
+ ILP64 and openblasCompat for LP64. This
+ is the default.
+
+
+
+
+ LAPACK
+ reference (also provides BLAS)
+
+
+ The Nixpkgs attribute is lapack-reference.
+
+
+
+
+ Intel
+ MKL (only works on x86 architecture)
+
+
+ The Nixpkgs attribute is mkl.
+
+
+
+
+ Introduced in PR
+ #83888, we are able to override the ‘blas’ and ‘lapack’
+ packages to use different implementations, through the
+ ‘blasProvider’ and ‘lapackProvider’ argument. This can be used
+ to select a different provider. For example, an overlay can be
+ created that looks like:
+
+
+self: super:
+
+{
+ blas = super.blas.override {
+ blasProvider = self.mkl;
+ }
+ lapack = super.lapack.override {
+ lapackProvider = self.mkl;
+ }
+}
+
+
+ This overlay uses Intel’s MKL library for both BLAS and LAPACK
+ interfaces. Note that the same can be accomplished at runtime
+ using LD_PRELOAD of libblas.so.3 and
+ liblapack.so.3.
+
+
+