Merge branch 'document-test-release' into 'main'

Draft documentation for upcoming release

See merge request !125

README.rst

@@ -296,3 +296,47 @@ Frequently asked questions
 Development
 -----------
 Developers documentation is available at development.rst.
+
+Upcoming release 24a (for alpha testing)
+----------------------------------------
+
+Work has started to provide newer toolchains and compiler versions. For these, the structure and layout of the modules has been modified compared to what is described above (the changes are experimentally and may change in the future, feedback is very welcome).
+
+To use the new compilers on the HPC system run::
+
+  mpsd-software 24a
+  module avail
+
+You get access (as of Dec 2023) to ``gcc/12.2.0`` (easybuild toolchain
+foss2022b), ``gcc/12.3.0`` (easybuild toolchain foss2023a), and ``gcc/13.2.0``
+(also via the toolchain gcc13 as easybuild did not yet release a toolchain with
+any gcc13 that we could mimic). The packages are currently only compiled on the
+Sandybridge architecture. They can be used on more modern architectures but will
+not make use of additional CPU features.
+
+When loading the toolchain metamodules (called ``toolchain/<easybuild version>|gcc<gcc major version>``), you will load (ignoring internal dependencies)
+
+- gcc
+- openmpi
+- fftw
+- openblas
+- scalapack
+
+Several additional octopus dependencies have also been compiled with all gcc
+versions. They can be loaded individually, we currently do not provide any
+metamodule for octopus dependencies. Please report any problems or missing
+modules, or difficulties loading modules that can come with or without MPI
+support.
+
+Each module sets an environment variable ``MPSD_<MODULE_NAME>_ROOT`` that can be used for configure and the rpath (see below).
+
+Spack requires adding rpath in the linker options (``LDLIBRARY_PATH`` is not set
+[and should not be set]), more details are available at:
+https://computational-science.mpsd.mpg.de/docs/mpsd-hpc.html#setting-the-rpath-finding-libraries-at-runtime
+(also https://docs.mpcdf.mpg.de/faq/hpc_software.html#how-do-i-set-the-rpath ).
+
+Setting the flags for all loaded modules should work via: ::
+
+  export LDFLAGS=`echo ${LIBRARY_PATH:+:$LIBRARY_PATH} | sed -e 's/:/ -Wl,-rpath=/g'`
+
+*Note* An intel toolchain may at some point also show up in the list. It might however not be functional yet so expect that loading that module might fail.