diff --git a/README.rst b/README.rst
index b562ba94859244cf6193f3590b628c503dbf8fc0..9b804cad58b0e37a7b20c8cb0a909cc5d8d8fb87 100644
--- a/README.rst
+++ b/README.rst
@@ -58,36 +58,10 @@ Use a console; navigate to the ``bfps`` folder, and type:
 **Full installation**
 
 If you want to run simulations on the machine where you're installing,
-you will need to call `compile_library` before installing.
+you will need to use `cmake` to compile and install the full library.
 Your machine needs to have an MPI compiler installed, the HDF5 C library
-and FFTW >= 3.4 --- a detailed prerequisite installation list is
+and FFTW >= 3.4 --- detailed instructions are
 included at the end of this document.
-The file `machine_settings_py.py` should be modified
-appropriately for your machine (otherwise the `compile_library` command will most
-likely fail).
-This file will be copied the first time you run `setup.py` into
-`$HOME/.config/bfps/machine_settings.py`, **where it will be imported from
-afterwards** --- any future edits **must** be made to the new file.
-You may, obviously, edit it afterwards and rerun the `compile_library` command as
-needed.
-
-.. code:: bash
-
-    python setup.py compile_library
-    python setup.py install
-
-For `machine_settings.py`, please keep in mind to turn on optimizations
-for production environments.
-In particular, for clusters of unknown architecture it helps to log into
-individual nodes and run the following command:
-
-.. code:: bash
-
-    gcc -march=native -Q --help=target
-
-The results can be used to then compile on the frontend node(s) without
-using `-march=native` (since the frontend node may have different
-architecture).
 
 -------------
 Documentation
@@ -96,8 +70,8 @@ Documentation
 While the code is not fully documented yet, basic information is already
 available, and it is recommended that you generate the manual and go
 through it carefully.
-Please don't be shy about asking for specific improvements to the
-current text.
+Please do ask for specific improvements to the current text where it is
+found lacking.
 In order to generate the manual, navigate to the repository folder, and
 execute the following commands:
 
@@ -127,79 +101,93 @@ Installation with prerequisites
 
 These installation steps assume that you have a working MPI compiler,
 properly configured on your system (i.e. the various configure scripts
-are able to find it).
-If this is not the case, please consult the FFTW and HDF5 compilation
-instructions for detailed instructions (`./configure --help` should be
-enough).
+are able to find it), as well as the `cmake` tool.
+We recommend to specify the desired MPI C++ compiler by exporting the
+environment variable `MPICXX` --- the BFPS cmake configuration looks for
+this variable.
+We also recommend that an environment variable `BFPS_OPTIMIZATION_FLAGS`
+is defined appropriately.
+In particular, for clusters of unknown architecture it helps to log into
+individual nodes and run the following command:
+
+.. code:: bash
+
+    gcc -march=native -Q --help=target
+
+Detailed full installation instructions:
 
-1. Make directory PREFIX on local fast partition.
+1. Make directory PREFIX on a local fast partition.
 
 2. Download, compile, install FFTW (latest version 3.x from http://www.fftw.org/).
    Execute the following commands in order, feel free to customize
    optimisation flags for your own computer (see http://www.fftw.org/fftw3_doc/Installation-on-Unix.html):
 
-.. code:: bash
+    .. code:: bash
 
-    ./configure --prefix=PREFIX --enable-float --enable-sse --enable-sse2 --enable-avx --enable-avx2 --enable-avx-128-fma --enable-avx512 --enable-mpi --enable-openmp --enable-threads
-    make
-    make install
-    ./configure --prefix=PREFIX  --enable-sse --enable-sse2 --enable-avx --enable-avx2 --enable-avx-128-fma --enable-avx512 --enable-mpi --enable-openmp --enable-threads
-    make
-    make install
+        ./configure --prefix=PREFIX --enable-float --enable-sse --enable-mpi --enable-openmp --enable-threads
+        make
+        make install
+        ./configure --prefix=PREFIX  --enable-sse2 --enable-avx512 --enable-mpi --enable-openmp --enable-threads
+        make
+        make install
 
-    BFPS will try to find HDF5 using the FindFFTW from the Morse project.
-    If the package is installed in a non standard location, it is recommanded
-    to setup the environment variables: FFTW_DIR (or FFTW_INCDIR and FFTW_LIBDIR)
+   BFPS will try to find FFTW using the FindFFTW from the Morse project.
+   If the package is installed in a non standard location, it is recommanded
+   to setup the environment variables: FFTW_DIR (or FFTW_INCDIR and FFTW_LIBDIR).
 
 3. Download, compile, install HDF5 (version 1.8.x, currently available
    at https://portal.hdfgroup.org/display/support/HDF5+1.8.20#files).
-   We are using parallel I/O, therefore we use the plain C interface of HDF5:
+   We are using parallel I/O, therefore we must use the plain C interface of HDF5:
 
-.. code:: bash
+    .. code:: bash
 
-    ./configure --prefix=PREFIX --enable-parallel
-    make
-    make install
-    
-    BFPS will try to find HDF5 using the regular FindHDF5.
-    Therefore, if the package is installed in a non standard location, it is recommanded
-    to setup the environment variable: HDF5_ROOT
+        ./configure --prefix=PREFIX --enable-parallel
+        make
+        make install
 
-3. This step may be ommited.
-   I recommend the creation of a virtual python3 environment (also under PREFIX) that will be used for installing bfps and dependencies.
+   BFPS will try to find HDF5 using the regular FindHDF5.
+   Therefore, if the package is installed in a non standard location, it is recommanded
+   to setup the environment variable: HDF5_ROOT.
+
+3. Optional.
+   We recommend the creation of a virtual python3 environment (also under PREFIX) that will be used for installing bfps and dependencies.
    Please see https://docs.python-guide.org/dev/virtualenvs/.
 
 4. Clone bfps repository.
 
-.. code:: bash
+    .. code:: bash
 
-    git clone git@gitlab.mpcdf.mpg.de:clalescu/bfps.git
+        git clone git@gitlab.mpcdf.mpg.de:clalescu/bfps.git
 
 5. Go into bfps repository, execute
 
-.. code:: bash
+    .. code:: bash
 
-    mkdir build
-    cd build
-    cmake ..
-    # possibly : cmake .. -DCMAKE_INSTALL_PREFIX=INSTALL_DIR
-    make ..
-    # to get a verbose compilation process, use VERBOSE=1 make
-    # make install
-
-6. Using BFPS from an external project. Along with all the BFPS files
-   (lib and headers) can be found different cmake files
-   that contains all the information related to the compilation of BFPS.
-   It is possible to load this file in another CMake based application
-   to know the dependencies and paths.
-   
-   For instance, the installation will create these files:
-   
-.. code:: bash
-    -- Installing: install/lib/BFPSConfig.cmake
-    -- Installing: install/lib/BFPS_EXPORT.cmake
-    -- Installing: install/lib/BFPS_EXPORT-noconfig.cmake
-    
-    In case an information is not provided, it is necessary to update
-    the cmake input config file: bfps/cmake/BFPSConfig.cmake.in
+        mkdir build
+        cd build
+        cmake ..
+        # possibly : cmake .. -DCMAKE_INSTALL_PREFIX=INSTALL_DIR
+        make
+        # to get a verbose compilation process, use
+        VERBOSE=1 make
+        make install
+
+6. If you used a custom install location (i.e. `CMAKE_INSTALL_PREFIX`)
+   you must include this location in the environment variable
+   `CMAKE_PREFIX_PATH`.
+   This ensures that the required `BFPSConfig.cmake` file is accessible for
+   future use by the package.
+
+7. Using BFPS from an external project.
+   BFPS creates and installs 3 files alongside the C++ headers and
+   library:
+
+    .. code:: bash
+
+        -- Installing: install/lib/BFPSConfig.cmake
+        -- Installing: install/lib/BFPS_EXPORT.cmake
+        -- Installing: install/lib/BFPS_EXPORT-noconfig.cmake
+
+   In case these files provide incomplete information, it is necessary to update
+   the cmake input config file: bfps/cmake/BFPSConfig.cmake.in.