ENH: amended documentation and changed env-vars as suggested

Also added a test to travis (apparently ATLAS=None... is not tested
on circleCI).

Signed-off-by: Nick Papior <nickpapior@gmail.com>

1 files changed, 59 insertions, 1 deletions

diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst
index d224951dd..a9ec496c5 100644
--- a/doc/source/user/building.rst
+++ b/doc/source/user/building.rst
@@ -118,12 +118,70 @@ means that g77 has been used. If libgfortran.so is a dependency, gfortran
 has been used. If both are dependencies, this means both have been used, which
 is almost always a very bad idea.
 
+Accelerated BLAS/LAPACK libraries
+---------------------------------
+
+NumPy searches for optimized linear algebra libraries such as BLAS and LAPACK.
+There are specific orders for searching these libraries, as described below.
+
+BLAS
+~~~~
+
+The default order for the libraries are:
+
+1. MKL
+2. BLIS
+3. OpenBLAS
+4. ATLAS
+5. Accelerate (MacOS)
+6. BLAS (NetLIB)
+
+
+If you wish to build against OpenBLAS but you also have BLIS available one
+may predefine the order of searching via the environment variable
+``NPY_BLAS_ORDER`` which is a comma-separated list of the above names which
+is used to determine what to search for, for instance::
+
+      NPY_BLAS_ORDER=ATLAS,blis,openblas,MKL python setup.py build
+
+will prefer to use ATLAS, then BLIS, then OpenBLAS and as a last resort MKL.
+If neither of these exists the build will fail (names are compared
+lower case).
+
+LAPACK
+~~~~~~
+
+The default order for the libraries are:
+
+1. MKL
+2. OpenBLAS
+3. ATLAS
+4. Accelerate (MacOS)
+5. LAPACK (NetLIB)
+
+
+If you wish to build against OpenBLAS but you also have MKL available one
+may predefine the order of searching via the environment variable
+``NPY_LAPACK_ORDER`` which is a comma-separated list of the above names,
+for instance::
+
+      NPY_LAPACK_ORDER=ATLAS,openblas,MKL python setup.py build
+
+will prefer to use ATLAS, then OpenBLAS and as a last resort MKL.
+If neither of these exists the build will fail (names are compared
+lower case).
+
+
 Disabling ATLAS and other accelerated libraries
------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Usage of ATLAS and other accelerated libraries in NumPy can be disabled
 via::
 
+    NPY_BLAS_ORDER= NPY_LAPACK_ORDER= python setup.py build
+
+or::
+
     BLAS=None LAPACK=None ATLAS=None python setup.py build