From c447313318c5d0d76064271ca74dff0bce36af7d Mon Sep 17 00:00:00 2001
From: Reiner Jung <reiner.jung@email.uni-kiel.de>
Date: Tue, 18 May 2021 10:14:41 +0000
Subject: [PATCH] Update README.md
---
README.md | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 211 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index d7c47ad..328f97a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,213 @@
-# ECSA Uvic
+# ECSA Uvic - Setup
+This archive contains the instructions to setup and execute all
+experiments we performed with UVic. Please note that we performed
+all our experiments on Linux machines running Debian Buster on
+AMD64/Intel 64 bit CPUs.
+## Prerequisites
+
+- UVic
+ - Linux build tools, including gcc, gfortran, make, autoconf, automake
+ and libtool
+ - Netcdf library including development files
+ - UVic can be obtained from the University of Victoria, Canada
+- OceanDSL tooling
+ - Java 11 OpenJDK or compatible including the JDK
+ - Download the Kieker binary distribution
+ `https://kieker-monitoring.net/download/`
+- Other
+ - Git
+ - Bash
+
+## Preparations
+
+Create a workspace for the analyis, e.g., `experiments`, and switch to
+this directory.
+```
+mkdir experients
+cd experiments
+```
+
+Clone the *ecsa-uvic* git repository containing the setup scripts.
+```
+git clone https://git.se.informatik.uni-kiel.de/oceandsl/ecsa-uvic.git
+```
+
+Clone the *oceandsl-java-tools* or retrieve them from the replication
+package.
+```
+git clone https://git.se.informatik.uni-kiel.de/oceandsl/oceandsl-java-tools
+```
+
+Obtain the UVic code: http://terra.seos.uvic.ca/model/
+
+Clone the *kieker-lang-pack-c* repository.
+```
+git clone https://github.com/kieker-monitoring/kieker-lang-pack-c
+```
+
+## Java Tools
+
+Building the Java tools should be straight forward. Enter:
+```
+cd oceandsl-java-tools
+./gradlew clean build
+cd ..
+```
+
+Install both tools as follows:
+```
+tar -xpf oceandsl-java-tools/tools/create-architecture-model/build/distributions/create-architecture-model.tar
+tar -xpf oceandsl-java-tools/tools/pp-static-log/build/distributions/pp-static-log.tar
+```
+
+This creates two directories in your experiments folder containing
+the respective tools in a bin folder.
+
+## Install Kieker
+
+Kieker is only needed in case you want to reproduce the dynamic analysis
+i.e., the observation of the model behavior at runtime.
+
+```
+cd kieker-lang-pack-c
+```
+
+Follow the installation instructions there. In short perform the following
+
+```
+libtoolize
+aclocal
+automake --add-missing
+autoconf
+```
+
+Then compile and install the monitoring probes.
+```
+./configure ; make
+```
+
+You may also call `make install`. However, this may require admin
+privileges.
+
+Switch back to the experiments directory
+```
+cd ..
+```
+
+From the Kieker binary distribution archive, extract the file
+`kieker-1.14/tools/collector-1.14.zip` from the archive.
+Then unpack the tool as follows:
+```
+unzip collector.zip
+```
+
+This installs the collector tool alongside the two tools from OceanDSL.
+
+Please note: You can also use the more recent binary distribution
+kieker-1.15-SNAPSHOT.
+
+## Setting up the Experiments
+
+Lets assume you are in the main `experiments` folder.
+Switch to `ecsa-uvic`.
+```
+cd ecsa-uvic
+```
+
+Here you need to create a `config` file. There are examples of the
+file available. Lets assume your user account is called `trillian` and
+the home directory is `/home/trillian` containing the `experiments`
+folder. Then the configuration file may look like this:
+
+```
+# Library path including Kieker libraries
+export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/home/rju/experiments/kieker-lang-pack-c/libkieker/.libs"
+
+# Compile configuration for kieker
+export CONFIGURATION="${BASE_DIR}/linux_amd64_gfortran_kieker"
+
+# Location for the observed monitoring data for each model variant
+export DATA_PATH="/home/rju/share/log-data/uvic"
+
+# Location for dynamic and static data
+export DYNAMIC_DATA_PATH="${DATA_PATH}/kieker-20210318-075550-28503821603624986-UTC--uvic-part"
+export STATIC_DATA_PATH="/home/trillian/uvic/static-data"
+
+# prepocessor
+PREPROCESS="$BASE_DIR/../pp-static-log/bin/pp-static-log"
+
+# arcitecture analysis tool
+ANALYSIS="$BASE_DIR/../create-architecture-model/bin/create-architecture-model"
+
+# addr2line
+ADDR2LINE=`which addr2line`
+
+# Path to the executable
+EXECUTABLE="/home/trillian/experiments/uvic/uvic-model/uvic-run-1/UVic_ESCM"
+
+# Dynamic and static prefix
+DYNAMIC_PREFIX="/home/trillian/experiments/uvic/uvic-model/uvic-run-1/code/"
+STATIC_PREFIX="/home/trillian/PlayPython/resources/preprocessed/"
+
+# Hostname where the dynamic analysis was executed
+HOST=node1
+```
+
+Of course the HOST variable must be changed to the name of the machine
+the experiments are run.
+
+The next file you have to create is a list of all experiments you want
+to run. The file must be named `experiments`. A list of all experiments
+which are used in the tutorial of MITgcm are listed in `tutorials` and
+all other experiments are listed in `normal`.
+
+## Compilation
+
+To compile the model follow the instructions in the UVic README.
+As configuration files, we used the `mk.in` and `control.in` files.
+
+## Run the Experiment
+
+To run the expriment, enter the `experiments/ecsa-uvic` directory and
+run `./run-dynamic-analysis.sh`. This will start the collector and
+subsequently the model.
+
+## Static Analysis
+
+-- added here --
+
+## Architecture Reconstruction
+
+Lets assume you have collected the dynamic and static data for the
+UVic experiment and you are in the `experiments/ecsa-uvic` directory.
+Now you can run the analysis for the experiment with
+
+`./run-architecture-analysis.sh`
+
+If everything is setup properly, you will get results files for the
+various analyses:
+- `dynamic-result` contains CSV files for various graphs of the
+ architecture model and dot files for the operation and component
+ view of the analysis. A graphml file is also generated. The files
+ follow a naming scheme EXPERIMENT-TYPE-CONTENT.EXTENSION where:
+ - EXPERIMENT is the name of the experiment
+ - TYPE is either *file* for each file is seen as a module or component
+ or *map* using a map file to group operations/files to modules.
+ - CONTENT describes what the file contains, e.g.,
+ `dynamic-distinct-function-degree`.
+ - EXTENSION refers to the proper file-type extension, e.g., csv.
+- `dynamic-model` contains for each experiment two subfolders for
+ *file* and *map* based architecture. Each folder contains an dump
+ of the internal architectural model as a set of XMI files.
+- `combined-result` contains the same files as the `dynamic-result but
+ now also the data from the static analysis has been used.
+- `combined-model` similar to `dynamic-model`, but these models reflect
+ the architecture after the dynamic and static analysis.
+
+## Additional Information
+
+You can use the `dotPic-fileConverter.sh` from the Kieker archive to
+convert all dot files. This tool requires `dot` installed on your
+machine.
--
GitLab