DOC: some more cleanup in INSTALL.txt, and rename to INSTALL.rst.txt

1 files changed, 149 insertions, 0 deletions

diff --git a/INSTALL.rst.txt b/INSTALL.rst.txt
new file mode 100644
index 000000000..41f23b8d0
--- /dev/null
+++ b/INSTALL.rst.txt
@@ -0,0 +1,149 @@
+Building and installing NumPy
++++++++++++++++++++++++++++++
+
+**IMPORTANT**: the below notes are about building Numpy, which for most users
+is *not* the recommended way to install Numpy.  Instead, use either a complete
+scientific Python distribution (recommended) or a binary installer - see
+http://scipy.org/install.html.
+
+
+.. Contents::
+
+Prerequisites
+=============
+
+Building NumPy requires the following software installed:
+
+1) For Python 2, Python__ 2.6.x or newer.
+   For Python 3, Python__ 3.2.x or newer.
+
+   On Debian and derivative (Ubuntu): python python-dev
+
+   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.19 (for development versions of numpy, not for released
+                   versions)
+3) nose__ (optional) 1.0 or later
+
+   This is required for testing numpy, but not for using it.
+
+Python__ http://www.python.org
+nose__ http://somethingaboutorange.com/mrl/projects/nose/
+
+
+.. note:: 
+
+   If you want to build Numpy in order to work on Numpy itself, use
+   ``runtests.py``.  For more details, see
+   http://docs.scipy.org/doc/numpy-dev/dev/development_environment.html
+
+.. note::
+
+   More extensive information on building Numpy (and Scipy) is maintained at
+   http://scipy.org/scipylib/building/index.html
+
+
+Basic Installation
+==================
+
+To install numpy run::
+
+    python setup.py build -j 4 install --prefix $HOME/.local
+
+This will compile numpy on 4 CPUs and install it into the specified prefix.
+To perform an inplace build that can be run from the source folder run::
+
+    python setup.py build_ext --inplace -j 4
+
+The number of build jobs can also be specified via the environment variable
+NPY_NUM_BUILD_JOBS.
+
+
+Choosing compilers
+==================
+
+On OS X and Linux, all common compilers will work.  Note that for Fortran,
+``gfortran`` is strongly preferred over ``g77``, but if you happen to have both
+installed then ``g77`` will be detected and used first.  To explicitly select
+``gfortran`` in that case, do::
+
+    python setup.py build --fcompiler=gnu95
+
+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 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__ http://mingwpy.github.io
+
+
+Building with optimized BLAS support
+====================================
+
+Configuring which BLAS/LAPACK is used if you have multiple libraries installed,
+or you have only one installed but in a non-standard location, is done via a
+``site.cfg`` file.  See the ``site.cfg.example`` shipped with Numpy for more
+details.
+
+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 <http://mingwpy.github.io/blas_lapack.html>`_.
+
+OS X
+----
+
+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.
+
+Ubuntu/Debian
+-------------
+
+In order to build with optimized a BLAS providing development package must be installed.
+Options are for example:
+
+ - ``libblas-dev``: reference BLAS (not very optimized)
+ - ``libatlas-base-dev``: generic tuned ATLAS, it is recommended to tune it to
+   the available hardware, see /usr/share/doc/libatlas3-base/README.Debian for
+   instructions
+ - ``libopenblas-base``: fast and runtime detected so no tuning required but a
+   very recent version is needed (>=0.2.15 is recommended).  Older versions of
+   OpenBLAS suffered from correctness issues on some CPUs.
+
+The actual implementation can be exchanged also after installation via the
+alternatives mechanism::
+
+    update-alternatives --config libblas.so.3
+    update-alternatives --config liblapack.so.3
+
+Or by preloading a specific BLAS library with::
+
+    LD_PRELOAD=/usr/lib/atlas-base/atlas/libblas.so.3 python ...
+
+
+Build issues
+============
+
+If you run into build issues and need help, the Numpy
+`mailing list <http://scipy.org/scipylib/mailing-lists.html>`_ is the best
+place to ask.  If the issue is clearly a bug in Numpy, please file an issue (or
+even better, a pull request) at https://github.com/numpy/numpy.