From ecb03886e0a32ccfacbcc78508a57c9227b8fd78 Mon Sep 17 00:00:00 2001
From: FKHals <5229803-FKHals@users.noreply.gitlab.com>
Date: Fri, 30 Sep 2022 11:05:02 +0200
Subject: [PATCH] Add user documentation for building and usage

---
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/README.md b/README.md
index 67f7c277eb..712582fba2 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,40 @@
+# Custom Open MPI
+
+A modified version of OpenMPI that makes it possible to extract the identity and swap/permutate ranks of OMPI-processes inside the same job using an external agent connected via TCP.
+
+## Building
+
+1. install/download dependencies (example for Fedora Linux)
+```shell
+sudo dnf install -y m4 autoconf automake libtoolize flex
+git submodule update --init --recursive
+```
+2. configure the build environment and install Open MPI in the current directory in the subdirectory `openmpi-install/` (if you want to benchmark: deactivate the debugging build by adding: `--with-platform=optimized` to `configure`)
+```shell
+./autogen.pl
+./configure --prefix=$(pwd)/openmpi-install 2>&1 | tee config.out
+```
+3. actually build it (using all cores, see [source](https://www.math-linux.com/linux/tip-of-the-day/article/speedup-gnu-make-build-and-compilation-process))
+```shell
+NB_CORES=$(grep -c '^processor' /proc/cpuinfo)
+make -j$((NB_CORES+1)) -l${NB_CORES} 2>&1 | tee make.out
+make install 2>&1 | tee install.out
+```
+
+The Step **3.** can be used the rebuild it after doing changes to the source code without needing to reconfigure everything again (which takes quite some time and is unnecessary if the configuration has not been changed).
+
+## Usage
+
+Two Components are used for testing which both reside in the subdirectory `rank-swapper-agent/`.
+For Testing compile the client and server programs with:
+```shell
+cd rank-swapper-agent
+make all
+```
+Now run the two scripts first `./server.sh` and then `./client.sh` in two separate terminal windows to observe that the clients (the MPI-processes) inform the server of their identity an then the server answers with modified ranks which the client then applies, completing it's initialization.
+
+**Now follows the actual/default Open MPI README:**
+
 # Open MPI
 
 The Open MPI Project is an open source Message Passing Interface (MPI)
-- 
GitLab