Skip to content

Commit f29c774

Browse files
AlexanderSchultheissibbem
AlexanderSchultheiss
authored and
ibbem
committed
Working on READMEs
1 parent 596949c commit f29c774

4 files changed

Lines changed: 141 additions & 40 deletions

File tree

‎INSTALL.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Installation
2+
## Installation Instructions
3+
In the following, we describe how to build the Docker image and run the experiments in Docker containers.
4+
5+
### Install Docker (if required)
6+
How you can install Docker depends on your OS.
7+
#### Windows or Mac
8+
You can find download and installation instructions [here](https://www.docker.com/get-started).
9+
#### Linux Distributions
10+
How you can install Docker on your system, depends on your distribution. However, the chances are high that Docker is part of your distributions package database.
11+
Docker's [documentation](https://docs.docker.com/engine/install/) contains instructions for common distributions.
12+
13+
### Open a suitable terminal
14+
```
15+
# Windows Command Prompt:
16+
- Press 'Windows Key + R' on your keyboard
17+
- Type in 'cmd'
18+
- Click 'OK' or press 'Enter' on your keyboard
19+
20+
# Windows PowerShell:
21+
- Open the search bar (Default: 'Windows Key') and search for 'PowerShell'
22+
- Start the PowerShell
23+
24+
# Linux:
25+
- Press 'ctrl + alt + T' on your keyboard
26+
```
27+
### Build the Docker container
28+
To build the Docker container you can run the build script corresponding to your OS
29+
```
30+
# Windows:
31+
.\build.bat
32+
# Linux/Mac (bash):
33+
./build.sh
34+
```
35+
36+
### Validation & expected output
37+
38+
#### Running the validation
39+
To run the validation you can run the script corresponding to your OS with `validation` as first argument
40+
```
41+
# Windows:
42+
.\execute.bat validation
43+
# Linux/Mac (bash):
44+
./execute.sh validation
45+
```
46+
The results of the validation are stored in the [results](results) directory.
47+
48+
#### Expected output of the validation
49+
The aggregated results of the validation can be found in the following files.
50+
51+
- The [speed statistics](results/difftrees/speedstatistics.txt) contain information about the total runtime, median runtime, mean runtime, and more:
52+
```
53+
#Commits: 14527
54+
Total commit process time is: 12.427866666666667min
55+
Fastest commit process time is: df4a1fa9c5cc5d54a9347a2bf4843cae87a942f1___xorg-server___0ms
56+
Slowest commit process time is: 9838b7032ea9792bec21af424c53c07078636d21___xorg-server___14578ms
57+
Median commit process time is: 6dc71f6b2c7ff49adb504426b4cd206e4745e1e3___xorg-server___19ms
58+
Average commit process time is: 51.330075032697735ms
59+
```
60+
- The [classification results](results/difftrees/ultimateresult.metadata.txt) contain information about how often each pattern was found, and more.
61+
```
62+
repository: <NONE>
63+
total commits: 18046
64+
filtered commits: 593
65+
failed commits: 0
66+
empty commits: 2926
67+
processed commits: 14527
68+
tree diffs: 55008
69+
fastestCommit: df4a1fa9c5cc5d54a9347a2bf4843cae87a942f1___xorg-server___0ms
70+
slowestCommit: 9838b7032ea9792bec21af424c53c07078636d21___xorg-server___14578ms
71+
runtime in seconds: 747.5400000000001
72+
runtime with multithreading in seconds: 137.22
73+
treeformat: diff.difftree.serialize.treeformat.CommitDiffDiffTreeLabelFormat
74+
nodeformat: mining.formats.ReleaseMiningDiffNodeFormat
75+
edgeformat: mining.formats.DirectedEdgeLabelFormat with mining.formats.ReleaseMiningDiffNodeFormat
76+
analysis: mining.strategies.PatternValidation
77+
#NON nodes: 0
78+
#ADD nodes: 0
79+
#REM nodes: 0
80+
filtered because not (is not empty): 132
81+
AddToPC: { total = 260536; commits = 12703 }
82+
AddWithMapping: { total = 27720; commits = 1447 }
83+
RemFromPC: { total = 235017; commits = 11830 }
84+
RemWithMapping: { total = 15381; commits = 1361 }
85+
Specialization: { total = 4662; commits = 624 }
86+
Generalization: { total = 7397; commits = 564 }
87+
Reconfiguration: { total = 2231; commits = 258 }
88+
Refactoring: { total = 5769; commits = 921 }
89+
Untouched: { total = 0; commits = 0 }
90+
#Error[#else after #else]: 2
91+
#Error[#endif without #if]: 8
92+
#Error[#else or #elif without #if]: 9
93+
#Error[not all annotations closed]: 6
94+
```
95+
96+
- The [runtime histogram](results/runtime_histogram.png) of each processed commit.
97+
![](docs/validation/validation_histogram.png)
98+
99+
100+
## Troubleshooting
101+
102+
### Got permission denied while trying to connect to the Docker daemon socket
103+
`Problem:` This is a common problem under Linux, if the user trying to execute Docker commands does not have the permissions to do so.
104+
105+
`Fix:` You can fix this problem by either following the [post-installation instructions](https://docs.docker.com/engine/install/linux-postinstall/), or by executing the scripts in the replication package with elevated permissions (i.e., `sudo`)
106+
107+
### Unable to find image 'replication-package:latest' locally
108+
`Problem:` The Docker container could not be found. This either means that the name of the container that was built does not fit the name of the container that is being executed (this only happens if you changed the provided scripts), or that the Docker container was not built yet.
109+
110+
`Fix:` Build the Docker container.
111+

‎README.md‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -18,27 +18,29 @@ Our appendix consists of:
1818
4. The complete results of our validation for all 44 datasets.
1919

2020
## DiffDetective
21-
We offer a [Docker](https://www.docker.com/) setup to easily replicate our validation with _DiffDetective_.
21+
We offer a [Docker](https://www.docker.com/) setup to easily __replicate__ our validation with _DiffDetective_.
22+
You can find detailed information on how to install Docker and build the container in the [INSTALL](Install.md) file.
2223

2324
### 1. Build the Docker container
24-
To build the Docker container you can
25-
- call Docker directly: `docker build -t replication-package .`
26-
- or execute the build script for your OS
27-
- Windows: `.\build.bat`
28-
- Linux/Mac (bash): `./build.sh`
25+
To build the Docker container you can run the _build_ script corresponding to your OS.
26+
#### Windows:
27+
> .\build.bat
28+
#### Linux/Mac (bash):
29+
> ./build.sh
2930
3031
### 2. Start the replication
31-
To execute the replication you can
32-
- call Docker directly: `docker run --rm -v "$./results":"/home/sherlock/results" replication-package replication`
33-
- or execute the script corresponding to your OS
34-
- Windows: `.\execute.bat replication`
35-
- Linux/Mac (bash): `./execute.sh replication`
36-
37-
```
38-
The replication will at least require several hours and might require up to a few days depending on your system.
39-
Therefore, we offer a short validation (5-10 minutes) which runs _DiffDetective_ on only four of the datasets.
40-
You can run it by providing "validation" as argument instead of "replication" (i.e., ./execute.sh validation).
41-
```
32+
To execute the replication you can run the _execute_ script corresponding to your OS with `replication` as first argument.
33+
34+
> The replication will at least require several hours and might require up to a few days depending on your system.
35+
> Therefore, we offer a short validation (5-10 minutes) which runs _DiffDetective_ on only four of the datasets.
36+
> You can run it by providing "validation" as argument instead of "replication" (i.e., ./execute.sh validation).
37+
38+
#### Windows:
39+
> .\execute.bat replication
40+
#### Linux/Mac (bash):
41+
> ./execute.sh replication
42+
43+
4244

4345
### 3. View the results in the [results](results) directory
4446
All raw results are stored in the [results](results) directory. The aggregated results can be found in the following files:
@@ -54,10 +56,11 @@ Instructions for manually installing Stack are given in [proofs/REQUIREMENTS.md]
5456
How to build our library and how to run the example is described in the [proofs/INSTALL.md](proofs/INSTALL.md).
5557

5658
### Running the example with Docker
57-
First, you have to build the Docker container as described above in the _DiffDetective_ section. Then, you can
58-
- call Docker directly: `docker run --rm -v "$./results":"/home/sherlock/results" replication-package proofs`
59-
- or execute the script corresponding to your OS
60-
- Windows: `.\execute.bat proofs`
61-
- Linux/Mac (bash): `./execute.sh proofs`
59+
First, you have to build the Docker container as described above in the _DiffDetective_ section.
60+
Then, you can run the _execute_ script corresponding to your OS with `proofs` as first argument.
61+
#### Windows:
62+
> .\execute.bat proofs
63+
#### Linux/Mac (bash):
64+
> ./execute.sh proofs
6265
6366
[haskell]: https://www.haskell.org/

‎docs/validation/validation_histogram.png‎

156 KB
Loading

‎proofs/INSTALL.md‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -28,24 +28,11 @@ stack run
2828

2929
### Option 2: Setup via Dockerfile
3030

31-
First, install [Docker](https://www.docker.com/).
32-
Second, open a terminal and navigate to the repository's directory (the directory containing this `INSTALL.md`).
33-
```shell
34-
cd <path/to/this/repository>
35-
```
36-
Third, create the docker image:
37-
```shell
38-
docker build -t ftr .
39-
```
40-
You can verify that the image was created successfully by running
41-
```shell
42-
docker images
43-
```
44-
and checking that an image called `ftr` is listed.
45-
Fourth, you can run the image and thus the demo:
46-
```shell
47-
docker run -t ftr
48-
```
31+
#### Building the container
32+
To build the required container, you can follow the instructions provided in the main [INSTALL](../INSTALL.md) file.
33+
Afterwards, you can run the _execute_ script corresponding to your OS with `proofs` as first argument
34+
- Windows: `.\execute.bat proofs`
35+
- Linux/Mac (bash): `./execute.sh proofs`
4936

5037
## What Is There to See
5138

0 commit comments

Comments
 (0)