Add README

README.md

+# hpc-benchmark-game
+
+The HPC Benchmark Game is a collection of 5 benchmark programs, each implemented in up to 5 programming languages. The intention was to compare the impact of the programming language on runtime, energy and memory usage. Unlike its namesake, the Computer Language Benchmark Game, this focuses on parallelized, HPC-adjacent applications.
+
+## Getting the source code
+
+This repository includes the EMA library as a submodule. You either need to do a recursive clone, or initialize the submodules afterwards.
+
+```bash
+$ git clone --recursive https://gitup.uni-potsdam.de/dostoll/hpc-benchmark-game
+# or
+$ git clone https://gitup.uni-potsdam.de/dostoll/hpc-benchmark-game
+$ git submodule update --recursive --init
+```
+
+Be aware that as of the time of writing, the EMA repository (https://git.gfz-potsdam.de/naaice/ema) is not publicly accessible!
+
+## Building the programs
+
+The easiest way to build the provided programs is by using the included Dockerfile. It creates a fully reproducible build and runtime environment, based on Fedora 40. It will also automatically validate all programs against the reference implementation.
+
+```bash
+$ docker build -t hpc-benchmark-game .
+# or
+$ podman build -t hpc-benchmark-game .
+```
+
+If you want or must build the programs yourself, just follow the steps from the Dockerfile and ignore everything that looks out of place. You will need compilers for C, C++ and Fortran, as well as a recent version of meson.
+
+```bash
+$ meson setup build
+$ meson compile -C build
+```
+
+By default, meson will build with `-march=generic`. To build with `-march=native`, you need to explicitly add it. When building with LLVM, you might also need to add `-latomic` to the linker arguments of each language.
+
+```bash
+$ meson setup build -Dc_args="-march=native" -Dcpp_args="-march=native" -Dfortran_args="-march=native"
+```
+
+If you don't have access to the EMA library, you can still build the programs but you won't be able to do measurements. Add `-Dema-measure=false` to disable EMA.
+
+### Running the benchmarks
+
+When using the docker image, you first need to spawn a (temporary) container from it. The container needs to be privileged / running as root so that it can read the RAPL measurements from sysfs. If you don't plan to do energy measurements, you can ignore this setting.
+
+```bash
+$ docker run --privileged --rm -it -v $PWD/output:/output hpc-benchmark-game
+# or
+$ sudo podman run --privileged --rm -it -v $PWD/output:/output hpc-benchmark-game
+```
+
+Once you are inside the container, you can list the available programs, run the measurement scripts, or run a benchmark directly.
+
+```bash
+$ ls -l /opt/hpc-benchmark-game/bin
+$ measure-ca
+$ ca-c-gcc 1024 24
+```
+
+When building yourself using meson, you can use the following command to create a folder with all compiled programs. Or you can search them yourself in the meson build directory.
+
+```bash
+$ env DESTDIR="${PWD}/outdir" meson install -C build
+$ ./outdir/ca-c-gcc 1024 24
+```
+
+## I have no idea what you are talking about
+
+If you have questions, feel free to send me an email at [dorian.stoll@uni-potsdam.de](mailto:dorian.stoll@uni-potsdam.de)
+
+## Licensing
+
+Everything that I wrote myself is licensed under CC0. Basically, do whatever you want. This includes:
+* The Dockerfile
+* The meson build scripts
+* The measurement, validation and plotting scripts
+* The results of my measurements
+
+The benchmarks are governed by the license of their reference implementation.