DOC: update documentation on how to build NumPy

Closes gh-15151

[ci skip]

2 files changed, 39 insertions, 84 deletions

diff --git a/INSTALL.rst.txt b/INSTALL.rst.txt
index d6c42bad7..b33f93683 100644
--- a/INSTALL.rst.txt
+++ b/INSTALL.rst.txt
@@ -14,24 +14,17 @@ Prerequisites
 
 Building NumPy requires the following installed software:
 
-1) For Python 3, Python__ 3.5.x or newer.
+1) Python__ 3.6.x or newer.
 
-   On Debian and derivative (Ubuntu): python python-dev
+   Please note that the Python development headers also need to be installed,
+   e.g., on Debian/Ubuntu one needs to install both `python3` and
+   `python3-dev`. On Windows and macOS this is normally not an issue.
 
-   On Windows: the official python installer on Python__ is enough
-
-   Make sure that the Python package distutils is installed before
-   continuing. For example, in Debian GNU/Linux, distutils is included
-   in the python-dev package.
-
-   Python must also be compiled with the zlib module enabled.
-
-2) Cython >= 0.29.2 (for development versions of numpy, not for released
-                     versions)
+2) Cython >= 0.29.13
 
 3) pytest__ (optional) 1.15 or later
 
-   This is required for testing numpy, but not for using it.
+   This is required for testing NumPy, but not for using it.
 
 Python__ http://www.python.org
 pytest__ http://pytest.readthedocs.io
@@ -45,14 +38,14 @@ pytest__ http://pytest.readthedocs.io
 
 .. note::
 
-   More extensive information on building NumPy (and Scipy) is maintained at
+   More extensive information on building NumPy (and SciPy) is maintained at
    https://scipy.github.io/devdocs/building/
 
 
 Basic Installation
 ==================
 
-To install numpy run::
+To install NumPy, run::
 
     python setup.py build -j 4 install --prefix $HOME/.local
 
@@ -88,18 +81,18 @@ installed then ``g77`` will be detected and used first.  To explicitly select
 Windows
 -------
 
-On Windows, building from source can be difficult.  Currently, the most robust
-option is to use the Intel compilers, or alternatively MSVC (the same version
-as used to build Python itself) with Intel ifort.  Intel itself maintains a
-good `application note <https://software.intel.com/en-us/articles/numpyscipy-with-intel-mkl>`_
+On Windows, building from source can be difficult (in particular if you need to
+build SciPy as well, because that requires a Fortran compiler).  Currently, the
+most robust option is to use MSVC (for NumPy only). If you also need SciPy,
+you can either use MSVC + Intel Fortran or the Intel compiler suite.
+Intel itself maintains a good `application note
+<https://software.intel.com/en-us/articles/numpyscipy-with-intel-mkl>`_
 on this.
 
-If you want to use a free compiler toolchain, the recommended compiler is MingwPy__.
-The older MinGW32 compiler set used to produce older .exe installers for NumPy
-itself is still available at https://github.com/numpy/numpy-vendor, but not
-recommended for use anymore.
-
-MingwPy__ https://mingwpy.github.io
+If you want to use a free compiler toolchain, our current recommendation is to
+use Docker or Windows subsystem for Linux (WSL).  See
+https://scipy.github.io/devdocs/dev/contributor/contributor_toc.html#development-environment
+for more details.
 
 
 Building with optimized BLAS support
@@ -114,16 +107,16 @@ Windows
 -------
 
 The Intel compilers work with Intel MKL, see the application note linked above.
-MingwPy__ works with OpenBLAS.
+
 For an overview of the state of BLAS/LAPACK libraries on Windows, see
 `here <https://mingwpy.github.io/blas_lapack.html>`_.
 
-OS X
-----
+macOS
+-----
 
-OS X ships the Accelerate framework, which NumPy can build against without any
-manual configuration.  Other BLAS/LAPACK implementations (OpenBLAS, Intel MKL,
-ATLAS) will also work.
+You will need to install a BLAS/LAPACK library. We recommend using OpenBLAS or
+Intel MKL. Apple's Accelerate also still works, however it has bugs and we are
+likely to drop support for it in the near future.
 
 Ubuntu/Debian
 -------------
diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst
index 1588de964..fefbb4e0b 100644
--- a/doc/source/user/building.rst
+++ b/doc/source/user/building.rst
@@ -11,19 +11,11 @@ Prerequisites
 
 Building NumPy requires the following software installed:
 
-1) Python 2.7.x, 3.4.x or newer
+1) Python 3.6.x or newer
 
-   On Debian and derivatives (Ubuntu): python, python-dev (or python3-dev)
-
-   On Windows: the official python installer at
-   `www.python.org <https://www.python.org>`_ is enough
-
-   Make sure that the Python package distutils is installed before
-   continuing. For example, in Debian GNU/Linux, installing python-dev
-   also installs distutils.
-
-   Python must also be compiled with the zlib module enabled. This is
-   practically always the case with pre-packaged Pythons.
+   Please note that the Python development headers also need to be installed,
+   e.g., on Debian/Ubuntu one needs to install both `python3` and
+   `python3-dev`. On Windows and macOS this is normally not an issue.
 
 2) Compilers
 
@@ -42,19 +34,16 @@ Building NumPy requires the following software installed:
    NumPy does not require any external linear algebra libraries to be
    installed. However, if these are available, NumPy's setup script can detect
    them and use them for building. A number of different LAPACK library setups
-   can be used, including optimized LAPACK libraries such as ATLAS, MKL or the
-   Accelerate/vecLib framework on OS X.
+   can be used, including optimized LAPACK libraries such as OpenBLAS or MKL.
 
 4) Cython
 
-   To build development versions of NumPy, you'll need a recent version of
-   Cython.  Released NumPy sources on PyPi include the C files generated from
-   Cython code, so for released versions having Cython installed isn't needed.
+   For building NumPy, you'll need a recent version of Cython.
 
 Basic Installation
 ------------------
 
-To install NumPy run::
+To install NumPy, run::
 
     pip install .
 
@@ -62,10 +51,6 @@ To perform an in-place build that can be run from the source folder run::
 
     python setup.py build_ext --inplace
 
-The NumPy build system uses ``setuptools`` (from numpy 1.11.0, before that it
-was plain ``distutils``) and ``numpy.distutils``.
-Using ``virtualenv`` should work as expected.
-
 *Note: for build instructions to do development work on NumPy itself, see*
 :ref:`development-environment`.
 
@@ -83,7 +68,7 @@ For detailed info on testing, see :ref:`testing-builds`.
 Parallel builds
 ~~~~~~~~~~~~~~~
 
-From NumPy 1.10.0 on it's also possible to do a parallel build with::
+It's possible to do a parallel build with::
 
     python setup.py build -j 4 install --prefix $HOME/.local
 
@@ -95,22 +80,11 @@ to perform a parallel in-place build, run::
 The number of build jobs can also be specified via the environment variable
 ``NPY_NUM_BUILD_JOBS``.
 
-
-FORTRAN ABI mismatch
---------------------
-
-The two most popular open source fortran compilers are g77 and gfortran.
-Unfortunately, they are not ABI compatible, which means that concretely you
-should avoid mixing libraries built with one with another. In particular, if
-your blas/lapack/atlas is built with g77, you *must* use g77 when building
-numpy and scipy; on the contrary, if your atlas is built with gfortran, you
-*must* build numpy/scipy with gfortran. This applies for most other cases
-where different FORTRAN compilers might have been used.
-
 Choosing the fortran compiler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To build with gfortran::
+Compilers are auto-detected; building with a particular compiler can be done
+with ``--fcompiler``.  E.g. to select gfortran::
 
     python setup.py build --fcompiler=gnu95
 
@@ -118,14 +92,14 @@ For more information see::
 
     python setup.py build --help-fcompiler
 
-How to check the ABI of blas/lapack/atlas
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How to check the ABI of BLAS/LAPACK libraries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 One relatively simple and reliable way to check for the compiler used to build
 a library is to use ldd on the library. If libg2c.so is a dependency, this
-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.
+means that g77 has been used (note: g77 is no longer supported for building NumPy).
+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
 ---------------------------------
@@ -145,7 +119,6 @@ The default order for the libraries are:
 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
@@ -235,14 +208,3 @@ Additional compiler flags can be supplied by setting the ``OPT``,
 ``FOPT`` (for Fortran), and ``CC`` environment variables.
 When providing options that should improve the performance of the code ensure
 that you also set ``-DNDEBUG`` so that debugging code is not executed.
-
-
-Building with ATLAS support
----------------------------
-
-Ubuntu
-~~~~~~
-
-You can install the necessary package for optimized ATLAS with this command::
-
-    sudo apt-get install libatlas-base-dev