first draft of README

README.rst

@@ -67,39 +67,38 @@ Package sets and toolchains
     <https://docs.easybuild.io/common-toolchains/#common_toolchains_foss>`__).
 
   - all packages grouped together in a toolchain can be loaded together using
-    the `module load` command.
+    the ``module load`` command.
 
-    Example: the `foss2022a-serial` tool chain provides (in spack notation)::
+    Example: the ``foss2022a-serial`` tool chain provides (in spack notation)::
 
       - gcc@11.3.0
       - binutils@2.38+headers+ld
       - fftw@3.3.10+openmp~~mpi
       - openblas@0.3.20
 
-   - in addition to the Easybuild-driven choice of packages, there are
-     additional packages included in each package which support the build of
-     Octopus within these toolchains. For `foss2022a-serial` these packages
-     include::
-
-      - libxc@5.2.3       # octopus-dependencies:
-      - gsl@2.7.1
-      - sparskit@develop  # 2021.06.01
-      - nlopt@2.7.0
-      - libgd@2.2.4       # 2.3.1
-      - libvdwxc@0.4.0~~mpi
-      - nfft@3.2.4
-      - berkeleygw@2.1~~mpi~scalapack
-      - python@3.9.5
-      - cgal@5.0.3  # 5.2
-      - hdf5@1.12.2~mpi
-      - etsf-io@1.0.4
+  - in addition to the Easybuild-driven choice of packages, there are
+    additional packages included in each package which support the build of
+    Octopus within these toolchains. For ``foss2022a-serial`` these packages
+    include::
+
+     - libxc@5.2.3       # octopus-dependencies:
+     - gsl@2.7.1
+     - sparskit@develop  # 2021.06.01
+     - nlopt@2.7.0
+     - libgd@2.2.4       # 2.3.1
+     - libvdwxc@0.4.0~~mpi
+     - nfft@3.2.4
+     - berkeleygw@2.1~~mpi~scalapack
+     - python@3.9.5
+     - cgal@5.0.3  # 5.2
+     - hdf5@1.12.2~mpi
+     - etsf-io@1.0.4
 
 
 MPSD software releases
 ~~~~~~~~~~~~~~~~~~~~~~
 
-As `explained in the MPSD HPC documentation
-<https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html#software>`__, we
+As ``explained in the MPSD HPC documentation <https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html#software>``__, we
 label software releases available on the HPC using a naming scheme of the year
 (such as ``23``) and a letter starting from ``a``. There is an exception that
 the first available software version is ``dev-23a`` (starting with ``dev-`` to
@@ -112,7 +111,7 @@ For each MPSD software release, multiple toolchains and package sets are availab
     $> ./mpsd-software.py available dev-23a
 
     MPSD software release dev-23a, AVAILABLE for installation are
-    Toolchains: 
+    Toolchains:
         foss2021a-cuda-mpi
         foss2021a-mpi
         foss2021a-serial
@@ -129,11 +128,40 @@ Prerequisites
 
 What needs to be installed for the installation to succeed?
 
+1. ``mpsd-software.py`` installation requirements
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+- a recent version of Python3 (3.9 or newer)
+
+- an environment variable MPSD_MICROARCH to point to the correct microarchitecture of the computer
+- or the ``archspec`` command in the search path that can determine this.
+  Install ``archspec`` as ``pip install archspec`` or ``pipx install archspec``.
+  If you are on a MPSD-maintained linux laptop, you can probably also use
+  `apt-get install archspec`.
+- Optional: if the ``rich`` package is available, some output will be coloured. (Debian package: `python3-rich` or `pip install rich`)
+
+2. Spack requirements
++++++++++++++++++++++
+
+To be able to compile the toolchains, one needs standard build tools (required by spack). On Debian/Ubuntu, this includes the packages:
+
+autoconf
+automake
+build-essential
+ca-certificates
+coreutils
+curl
+file
+gfortran
+git
+libtool
+lmod
+openssh-server
+python3
+rsync
+unzip
+wget
+
 Probably an ongoing topic of work. We know the following tools need to be available:
 
 - XXX TODO, add, requirements in container from CI might be best. Things like rsync, git, buildtools, Linux-headers,
-
-
-
-
-