Updated with changes from submission

Author: AlexanderSchultheiss

Dockerfile

@@ -38,7 +38,7 @@ RUN cat ubuntu-repos.txt >> /etc/apt/sources.list
 RUN apt-get update \
     && apt-get install -y --no-install-recommends gcc-4.4
 RUN ln -s /bin/gcc-4.4 /bin/gcc
-RUN rm -rf VariabilityExtraction
+RUN rm -rf Extraction
 RUN gcc --version
 RUN java -version
 RUN apt-get install -y --no-install-recommends bc
@@ -47,15 +47,15 @@ RUN apt-get install -y --no-install-recommends bc
 WORKDIR /home/user
 # Copy JAR from previous stage
 COPY --from=0 /home/user/target /home/user/target
-RUN cp target/VariabilityExtraction-*-jar-with* .
+RUN cp target/Extraction-*-jar-with* .
 
 # Copy required scripts and properties
 COPY docker-resources/extract.sh /home/user/
 COPY docker-resources/entrypoint.sh /home/user/
 COPY docker-resources/fix-perms.sh /home/user/
 COPY docker-resources/KernelHaven.jar /home/user/
-COPY docker-resources/variability_analysis_BusyBox.properties /home/user/
-COPY docker-resources/variability_analysis_Linux.properties /home/user/
+COPY docker-resources/extraction_busybox.properties /home/user/
+COPY docker-resources/extraction_linux.properties /home/user/
 
 RUN mkdir -p /home/user/extraction-results/output
 RUN chown user:user /home/user -R

README.md

@@ -1,66 +1,68 @@
 # VEVOS: Ground Truth Extraction
-
 VEVOS is a tool suite for the simulation of the evolution of clone-and-own projects and consists of two main components: The ground truth extraction, called VEVOS/Extraction and the variant simulation called VEVOS/Simulation.
 
 This repository contains VEVOS/Extraction and thus the first part of the replication package for the paper _Simulating the Evolution of Clone-and-Own Projects with VEVOS_ submitted to the International Conference on Evaluation and Assessment in Software Engineering (EASE) 2022.
-VEVOS/Extraction is a java for extracting feature mappings, presence conditions, and feature models for each revision (withing a specified range of the commit-history) from an input software product line.
+VEVOS/Extraction is a java project for extracting feature mappings, presence conditions, and feature models for each revision (within a specified range of the commit-history) from an input software product line.
+
+![](docs/extraction.png)
 
 ## Quick Start using Docker
-In the following, we provide instructions on how to quickly extract the ground truth of Linux or Busybox with the provided 
-Docker setup.
+In the following, we provide instructions on how to quickly extract the ground truth of Linux or Busybox with the provided Docker setup.
 
 ### Requirements
 The only requirement is Docker. We provide batch and bash scripts that execute the necessary Docker setup and execution.
 We tested the Docker setup under Windows and Linux. 
-We have not tested the setup on Mac, but you should be able to use follow the instructions for Linux.
+We have not tested the setup on Mac, but you should be able to use the instructions for Linux.
 
 ### Preparation
 #### Docker
 Docker must be installed on your system, and the Docker daemon must be running.
-For installation, follow the instructions given in the installation guide for your OS which you can find 
+For installation, follow the instructions given in the installation guide for your OS which you can find
 [here](https://docs.docker.com/get-docker/).
-Under Linux, you should follow the optional 
+Under Linux, you should follow the optional
 [post-installation instructions](https://docs.docker.com/engine/install/linux-postinstall/).
 
 #### Repository
-Clone the repository to a location of your choice 
+Clone the repository to a location of your choice
 ```
-git clone https://github.com/VariantSync/Extraction.git
+git clone https://github.com/VariantSync/VEVOS_Extraction.git
 ``` 
-Then, navigate to the repository's root directory in a terminal of your choice. 
+Then, navigate to the repository's root directory in a terminal of your choice.
 
 ### Build the Docker Image
-Before the extraction can be executed, we have to build the Docker image. This can be done by executing the correspsonding build script in a terminal.
+Before the extraction can be executed, we have to build the Docker image. This can be done by executing the corresponding build script in a terminal.
 
 - Linux terminal: `./build-docker-image.sh`
 - Windows CMD: `build-docker-image.bat`
 
+This process may roughly take half an hour.
+
 ### Start the Ground Truth Extraction in a Docker Container
-We provide bash and batch scripts that start the ground truth extraction and copy all data to 
+We provide bash and batch scripts that start the ground truth extraction and copy all data to
 _Extraction/extraction-results_ once the extraction is complete, or has been stopped.
-Start the extraction by executing the `start-extraction` script (see examples further below). 
+Start the extraction by executing the `start-extraction` script (see examples further below).
 The basic syntax is the following:
 
 - `start-extraction.(sh|bat) (linux|busybox) [commit-id/tag] [commit-id/tag]`
-- `(option-1|option-2)` -> You *must* provide one of the two.
+- `(option-1|option-2)` -> You *must* provide either a value for `option-1` or `option-2`.
 - `[option]` -> You *may* provide a value
 
 The script must be provided with `busybox` or `linux` as first argument, in order to specify which SPL should be considered.
-In addition, you can optionally provide either one or two more arguments specifying a commit-id or git-tag. 
+In addition, you can optionally provide either one or two more arguments specifying a commit-id or git-tag.
 
 If you specify __no__ id or tag, the entire history is considered.
 
-If you specify __exactly one__ id or tag, the extraction will only consider the one commit that is found under the id/tag. 
-This can be used to quickly test whether everything is working as intended. 
+If you specify __exactly one__ id or tag, the extraction will only consider the one commit that is found under the id/tag.
+This can be used to quickly test whether everything is working as intended or to run the extraction for one commit only (e.g., when no evolution information is necessary).
 
 If you specify __two__ ids or tags, the extraction will consider the range of commits that lies between the first and the second
 commit. The commit retrieval follows the same logic as [git log](https://git-scm.com/docs/git-log), i.e., it will retrieve
 all commits that are ancestors of the second commit, but __not__ ancestors of the first commit.
 
-- Windows CMD: 
+- Windows CMD:
   - `start-extraction.bat busybox [id/tag] [id/tag]` 
   - `start-extraction.bat linux [id/tag] [id/tag]`
-- Linux terminal: 
+- Linux terminal:
   - `./start-extraction.sh busybox [id/tag] [id/tag]`
   - `./start-extraction.sh linux [id/tag] [id/tag]`
 
@@ -70,8 +72,8 @@ The entire history of BusyBox can be extracted in about one day.
 For Linux, even considering only the commits between two minor revisions, e.g. v4.1 and v4.2, can take several days.
 
 #### Errors in Log
-If the entire history of BusyBox or Linux is considered, large numbers of non-extractable commits are to be expected. 
-Therefore, errors that appear in the log do not indicate a problem with the setup, but only indicate that a commit could not be processed. 
+If the entire history of BusyBox or Linux is considered, non-extractable commits are to be expected.
+Therefore, errors that appear in the log do not necessarily indicate a problem with the setup, but only indicate that a commit could not be processed.
 
 #### Examples:
 ```
@@ -93,29 +95,29 @@ start-extraction.bat linux v4.3 v4.4
 ```
 
 ### Stopping the Ground Truth Extraction
-You can stop the Docker container in which the ground truth extraction is running at any time. In this case, all 
-collected data will be copied to _Extraction/extraction-results/_ as if the extraction finished successfully. 
+You can stop the Docker container in which the ground truth extraction is running at any time. In this case, all
+collected data will be copied to _Extraction/extraction-results/_ as if the extraction finished successfully.
 
-- Windows CMD: 
+- Windows CMD:
   - `stop-extraction.bat busybox`
   - `stop-extraction.bat linux`
-- Linux terminal: 
+- Linux terminal:
   - `./stop-extraction.sh busybox`
   - `./stop-extraction.sh linux`
 
 ### Custom Configuration
-You can find the properties files used by Docker under Extraction/docker-resources. By changing the properties 
-for BusyBox or Linux respectively, you can adjust the ground truth extraction (e.g., change the log level, 
+You can find the properties files used by Docker under Extraction/docker-resources. By changing the properties
+for BusyBox or Linux respectively, you can adjust the ground truth extraction (e.g., change the log level,
 number of threads, etc.). For your convenience, we set all properties to default values. __Note that you have to rebuild the Docker image in order for the changes to take effect__.
 
 This can also be used in case you want to extract the ground truth for any other SPL besides Linux and BusyBox. However,
 please note that this requires the correct configuration of KernelHaven and possibly other preprocessing steps, that
 are not included in this project. In addition, the extractors that are used internally, i.e., KbuildMiner and KconfigReader
-might not be applicable to the chosen SPL. In this case, custom extractors have to be implemented and added to the dependencies 
+might not be applicable to the chosen SPL. In this case, custom extractors have to be implemented and added to the dependencies
 in the _pom.xml_ file.
 
 ### Clean-Up 
-You clean up all created images, container, and volumes via `docker system prune -a`. __DISCLAIMER: This will remove ALL docker objects, even the ones not related to ground truth extraction__. If you have other images, containers, or volumes that you do not want to loose, you can run the docker commands that refer to the objects related to the ground truth extraction.
+You can clean up all created images, container, and volumes via `docker system prune -a`. __DISCLAIMER: This will remove ALL docker objects, even the ones not related to ground truth extraction__. If you have other images, containers, or volumes that you do not want to loose, you can run the docker commands that refer to the objects related to the ground truth extraction.
 - Image: `docker rmi extraction`
 - Container: 
   - `docker container rm extraction-busybox`
@@ -126,7 +128,7 @@ You clean up all created images, container, and volumes via `docker system prune
 
 ## Custom System Setup
 If you want to run the ground truth extraction without Docker, you will have to first set up the environment in which
-the extraction is executed. 
+the extraction is executed.
 
 ### Limitations
 There are some limitations to the ground truth extraction that should be mentioned.
@@ -159,7 +161,7 @@ It is possible to use WSL to run the extraction on a Windows machine.
 
 #### Installing WSL2 with Ubuntu 20 LTS
 - Follow the guide at https://docs.microsoft.com/en-us/windows/wsl/install-win10
-- Using WSL2 is strongly recommended, because the extraction under WSL1 will take a lifetime. You can check which WSL you 
+- Using WSL2 is strongly recommended, because the extraction under WSL1 will take a lifetime. You can check which WSL you
   have installed by following the instructions here https://askubuntu.com/questions/1177729/wsl-am-i-running-version-1-or-version-2
 - You can list the installed distributions with `wsl --list --verbose`
 - Install Ubuntu 20 LTS via the Microsoft store
@@ -265,7 +267,7 @@ git clone https://github.com/torvalds/linux.git
 
 Clone the Extraction repository:
 ```
-git clone [email protected]:mse/VariantSync/Extraction.git
+git clone https://github.com/VariantSync/VEVOS_Extraction.git
 ```
 
 Navigate into the repo:

docker-resources/extract.sh

@@ -13,26 +13,26 @@ then
     echo "Executing variability extraction of BusyBox."
     if [ $# == 1 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_BusyBox.properties
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_busybox.properties
     elif [ $# == 2 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_BusyBox.properties "$2"
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_busybox.properties "$2"
     elif [ $# == 3 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_BusyBox.properties "$2" "$3"
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_busybox.properties "$2" "$3"
     fi
 elif [ "$1" == 'linux' ]
 then
     echo "Executing variability extraction of Linux."
     if [ $# == 1 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_Linux.properties
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_linux.properties
     elif [ $# == 2 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_Linux.properties "$2"
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_linux.properties "$2"
     elif [ $# == 3 ]
     then
-        java -jar VariabilityExtraction-1.0.0-jar-with-dependencies.jar variability_analysis_Linux.properties "$2" "$3"
+        java -jar Extraction-1.0.0-jar-with-dependencies.jar extraction_linux.properties "$2" "$3"
     fi
 else
     echo "Select a SPL to extract from [ linux | busybox ]"

docker-resources/extraction_busybox.properties

@@ -44,7 +44,7 @@ analysis.number_of_tasks = 5
 #######################################
 
 # Do not change this
-analysis.class = de.variantsync.subjects.extraction.kh.VariabilityAnalysis
+analysis.class = de.variantsync.vevos.extraction.kh.VariabilityAnalysis
 preparation.class.0 = net.ssehub.kernel_haven.busyboot.PrepareBusybox
 analysis.output.type = csv
 

docker-resources/extraction_linux.properties

@@ -44,7 +44,7 @@ analysis.number_of_tasks = 3
 #######################################
 
 # Do not change this
-analysis.class = de.variantsync.subjects.extraction.kh.VariabilityAnalysis
+analysis.class = de.variantsync.vevos.extraction.kh.VariabilityAnalysis
 analysis.output.type = csv
 analysis.code_block.consider_missing_bm_infos = false