first draft of README

README.rst

-MPSD Software installation
-==========================
+MPSD Software manager
+=====================
 
 .. contents::
 
@@ -20,28 +20,45 @@ Quick start
 
 To install, for example, the ``foss2022a-serial`` toolchain:
 
-1. Clone this repository to the place where you want to install the software environment::
+1. Install this mpsd-software-manager Python package. The recommended way is to
+   use ``pipx`` to that this tool is available independent from the use of any
+   other python environments::
 
-     git clone https://gitlab.gwdg.de/mpsd-cs/mpsd-software.git
+     $ pipx install git+https://gitlab.gwdg.de/mpsd-cs/mpsd-software-manager
 
-2. ``cd mpsd-software``
 
-3. Execute the script to install the toolchain::
+2. Navigate to the location in your file system where you would like to store
+   the compiled software. (Once compiled, the location cannot be changed.) For
+   example::
 
-     $> ./mpsd-software.py install dev-23a foss2022a-serial
+     $ cd /home/user/mpsd-software
+
+
+3. Initiate the installation at this location using::
+
+     $ mpsd-software init
+
+   (This creates a hidden file ``.mpsd-software-root`` to tag the location for
+   as the root of the installation. All compiled files, logs etc are written in
+   or below this subdirectory.)
+
+4. From the same directory, run the command to install the ``foss2022a-serial``
+   toolchain::
+
+     $ mpsd-software install dev-23a foss2022a-serial
 
    This will take some time (up to several hours depending on hardware).
 
-4. To see the installation status, and the required ``module use`` command line
+5. To see the installation status, and the required ``module use`` command line
    to activate the created modules, try the ``status`` command::
 
-     $> ./mpsd-software status dev-23a
+     $ mpsd-software status dev-23a
 
      Installed toolchains (dev-23a):
 
      - cascadelake
          foss2022a-serial
-         [module use /home/fangohr/git/mpsd-software-environments/dev-23a/cascadelake/lmod/Core]
+         [module use /home/user/mpsd-software/dev-23a/cascadelake/lmod/Core]
 
 
 
@@ -67,39 +84,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
@@ -109,10 +125,10 @@ At the moment (June 2023), there is only one release (that is ``dev-23a``).
 
 For each MPSD software release, multiple toolchains and package sets are available::
 
-    $> ./mpsd-software.py available dev-23a
+    $> mpsd-software available dev-23a
 
     MPSD software release dev-23a, AVAILABLE for installation are
-    Toolchains: 
+    Toolchains:
         foss2021a-cuda-mpi
         foss2021a-mpi
         foss2021a-serial
@@ -129,11 +145,29 @@ Prerequisites
 
 What needs to be installed for the installation to succeed?
 
-Probably an ongoing topic of work. We know the following tools need to be available:
+The ``mpsd-software-manager`` python package.
+
+- This needs a recent Python (3.9 or later).
+- Install via pip or pipx.
+
+  Pipx commands are:
+  
+  - to install: ``pipx install git+https://gitlab.gwdg.de/mpsd-cs/mpsd-software-manager``
+  - to update: ``pipx upgrade mpsd-software-manager``
+  - to uninstall: ``pipx uninstall mpsd-software-manager``
+
+- Requirements to be able to run `spack <spack.readthedocs.io>`__
+
+  - Please check https://spack.readthedocs.io/en/latest/getting_started.html#system-prerequisites
+
 
-- XXX TODO, add, requirements in container from CI might be best. Things like rsync, git, buildtools, Linux-headers,
+The compilation of the ``*-mpi`` toolchains needs linux headers installed. (TODO Add more detail.)
 
+Working example
+~~~~~~~~~~~~~~~
 
+We have a continuous integration example at XXX, that shows the complete
+compilation cycle (including compilation of Octopus). (TODO)