Merge pull request #4 from VariantSync/experimental-virtualization

Experimental virtualization

Author: pmbittner

Dockerfile

@@ -23,11 +23,14 @@ RUN nix-build
 RUN mkdir -p /etc/fonts && nix-build nix/fontconfig.nix --out-link /etc/fonts/fonts.conf
 RUN mkdir -p /var/cache/fontconfig && nix-shell -p fontconfig --run fc-cache
 
+# We need `cp` to copy out the jar.
+RUN nix-build '<nixpkgs>' -A coreutils -o coreutils
+
 # Copy DiffDetective with all runtime dependencies (ignoring build-time
 # dependencies) to a separate folder. Such a subset of the Nix store is called a
 # closure and enables us to create a minimal Docker container.
 RUN mkdir closure
-RUN nix-store -qR result /etc/fonts/fonts.conf | xargs cp -Rt closure
+RUN nix-store -qR result /etc/fonts/fonts.conf coreutils | xargs cp -Rt closure
 
 # Start building the final container.
 FROM scratch
@@ -48,5 +51,8 @@ COPY data /home/user/data
 COPY --from=builder /etc/fonts/fonts.conf /etc/fonts/fonts.conf
 COPY --from=builder /var/cache/fontconfig /var/cache/fontconfig
 
+# Install `cp`
+COPY --from=builder /home/user/coreutils/bin/cp /bin/cp
+
 ENV DISPLAY=:0 HOME=/home/user
 CMD ["/DiffDetective/bin/DiffDetective-Demo"]

INSTALL.md

@@ -1,15 +1,21 @@
 # Setup Instructions
 
-You may run the demo manually, or by using Nix or Docker.
-The manual setup enables you to use DiffDetective in any of your own Maven projects.
-The Nix and Docker setups just build the demo for you to run it.
-Windows users should _not_ use the Nix setup except if they have experience with WSL2, XServers, and Nix (see [REQUIREMENTS.md](REQUIREMENTS.md)).
+You may build and run the demo _either_ manually _or_ by using Docker _or_ Nix.
 
-In case you encounter problems, you may have a look at the _Troubleshooting_ section at the bottom of this file.
+**The purpose of this demo is to serve as a template project for starting to develop with DiffDetective, as well as to give examples on how to use and integrate DiffDetective in your projects.
+We hence recommend the manual setup because it enables you to use DiffDetective in any of your own Maven projects.**
 
-## Manual Setup
+The Nix and Docker setups build the demo to a runnable jar file.
+We also provide scripts for running the Demo using Nix dependencies and inside Docker but we do not recommend the complete Docker setup because the demo launches a graphical user interface which frequently causes problems when inside of Docker (see Troubleshooting section at the bottom of this file).
+We hence recommend (1) to build either manually or with Nix or with Docker and (2) to run the produced jar file manually.
+(Windows users should _not_ use the Nix setup except if they are experts on WSL2, XServers, and Nix (see [REQUIREMENTS.md](REQUIREMENTS.md)).)
 
-Check the requirements needed for the manual setup in the [REQUIREMENTS.md](REQUIREMENTS.md) file.
+Once you decided for a setup (Manual/Docker/Nix), check the requirements needed for the respective setup in the [REQUIREMENTS.md](REQUIREMENTS.md) file.
+
+>In case you encounter problems during the setup, you may have a look at the _Troubleshooting_ section at the bottom of this file.
+
+
+## Manual Build
 
 Follow the setup instructions on the [DiffDetective website](https://variantsync.github.io/DiffDetective/) for building and installing DiffDetective with Maven (and _not_ with Nix).
 These instructions make you clone the repo and install it.
@@ -30,19 +36,26 @@ To run the demo, invoke `java` on the jar file that includes any dependencies:
 java -jar target/diffdetectivedemo-1.0.0-jar-with-dependencies.jar
 ```
 The expected output and behavior of the jar file is explained below in the section _Expected Output_.
+Make sure that you are at the top level of this repository in the terminal (i.e, the directory containing this INSTALL.md file).
 
-## Docker Setup
+## Automatic Build
 
-Check the requirements needed for the Docker setup in the [REQUIREMENTS.md](REQUIREMENTS.md) file.
+We provide two methods for automatically building this demo:
+- a [Docker](https://www.docker.com/get-started) build, and
+- a [Nix](https://nixos.org/download/) build.
+
+### Starting the docker deamon
 
-### Start the docker deamon
+If you want to use Docker to build the jar for you, Docker needs to be installed and running.
+Check the requirements needed for the Docker setup in the [REQUIREMENTS.md](REQUIREMENTS.md) file.
+You may also need to start the Docker daemon before any Docker commands can be run.
 
 - **On Linux**: Typically, the docker deamon runs automatically, so there is nothing to do. Otherwise, run `sudo systemctl start docker`.
 - **On Windows**: Open the search bar using the 'Windows Key' and search for 'Docker' or 'Docker Desktop'.
 
 More detailed instructions on starting the deamon are given [here](https://docs.docker.com/config/daemon/start/) on the docker website.
 
-### Docker Setup on Windows
+### Docker Build on Windows
 
 Open a terminal (preferably Windows PowerShell) and navigate to the repository's directory (the directory containing this `INSTALL.md`).
 Then, create the docker image
@@ -54,73 +67,80 @@ You can verify that the image was created successfully by running
 docker images
 ```
 and checking that an image called `diffdetective-demo` is listed.
-You can run the image and thus the demo with the following command:
+
+To extract the built jar you can run
 ```shell
-docker run --net=host -e DISPLAY=host.docker.internal:0 --volume="$PWD/data/output:/home/user/data/output:rw" -t diffdetective-demo
+docker run --volume "${pwd}:/output:rw" diffdetective-demo:1.0.0 /bin/cp /DiffDetective/share/java/DiffDetective-Demo.jar /output
 ```
-You may get some font errors, which you can ignore (see Troubleshooting below).
-The parameters `--net=host` and `-e DISPLAY=host.docker.internal:0` are required to launch graphical user interfaces from within Docker.
-
-### Docker Setup on Linux
-
-> You might require elevated privileges to execute Docker commands (e.g., `sudo ./docker.sh build` or adding the user to the `docker` or `wheel` group).
-> See Docker's [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) for more information.
+and execute it using
+````shell
+java -jar DiffDetective-Demo.jar
+````
+
+> **Experimental:**
+> Alternatively, You can run the image and thus the demo with the following command:
+> ```shell
+> docker run --net=host -e DISPLAY=host.docker.internal:0 --volume="$PWD/data/output:/home/user/data/output:rw" -t diffdetective-demo
+> ```
+> You may get some font errors, which you can ignore (see Troubleshooting below). 
+> The parameters `--net=host` and `-e DISPLAY=host.docker.internal:0` are required to launch graphical user interfaces from within Docker.
+
+### Nix or Docker Build on Linux
+
+You can use the `build-jar.sh` script to build the Demo jar using [Nix](https://nixos.org/download/) or [Docker](https://www.docker.com/get-started).
+The `build-jar.sh` script will automatically choose the build method depending on the available software (Nix or Docker, in that order).
+You might require elevated privileges to execute Docker commands (e.g., `sudo ./build-jar.sh` or adding the user to the `docker` or `wheel` group).
+See Docker's [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) for more information.
+Also, it is best to install required software (e.g., Nix, Docker) using your distro's package manager if it is available.
 
-> It is best to install required software (e.g., Docker, Maven) using your distro's package manager if it is available.
-
-You can use the `docker.sh` script to build and execute the Demo using [Docker](https://www.docker.com/get-started) as described below.
-
-#### Setup
 Clone and navigate to this repository (the directory containing this `INSTALL.md`).
-Then, simply build the image using the provided script:
+Then, simply build the jar using the provided script:
 ```shell
-./docker.sh build
+./build-jar.sh
 ```
 
-This will automatically build the Docker container using Nix if Nix is installed on your system.
+The jar can then be executed with
+````shell
+java -jar DiffDetective-Demo.jar
+````
 
-#### Execution
-Once the image has been build, you can start the demo with
-```shell
-./docker.sh demo
-```
+### Complete Docker Setup on Linux
 
-## Nix Setup
+> **Experimental:**
+> You can build and start a demo Docker container with
+> ```shell
+> ./docker.sh build
+> ./docker.sh demo
+> ```
 
-Nix can be used to reproducibly build both, a standalone derivation and a docker container.
-Nix aids in reproducible builds whereas Docker aids in reproducible execution.
+### Nix Build
 
+Nix can be used to reproducibly build this DiffDetective demo.
 To use Nix, you need to have [Nix](https://nixos.org/download/) installed on your system.
-See [REQUIREMENTS.md](REQUIREMENTS.md) for instructions on how to install Nix and optionally also Docker.
-
-### Standalone Build
+See [REQUIREMENTS.md](REQUIREMENTS.md) for instructions on how to install Nix.
 
 > Notice for Windows users:
 > You must run the following commands from within a WSL2 terminal.
 > Also, make sure to clone this repository to a directory within WSL and _not_ to a Windows directory.
 > Otherwise, the Nix setup might fail due to incompatibilities with the file system.
-> Moreover, if you would like to have access to the demo's GUI, you need an XServer installed (see [REQUIREMENTS.md](REQUIREMENTS.md)).
 
-Clone and navigate to this repository.
-Then simply build and run the Demo using
+> Notice for Nix flake users:
+> If you have flakes enabled, you can just use `nix run github:VariantSync/DiffDetective-Demo` to run the demo instead of the following instructions.
+
+Clone and navigate to this repository in a terminal.
+Then simply build the Demo with
 ```shell
 nix-build
-./result/bin/DiffDetective-Demo
 ```
 
-If you have flakes enabled, you can instead just use
+Afterwards, the produced jar file is located at `result/share/java/DiffDetective-Demo.jar`.
+You can run it manually with Java (requires Java 17 or higher):
 ```shell
-nix run github:VariantSync/DiffDetective-Demo
+java -jar result/share/java/DiffDetective-Demo.jar
 ```
-
-### Using a Docker Image
-
-If you have Nix installed, the `docker.sh` script will automatically build this demo using Nix.
-Hence, the instructions are the same as for docker:
-Clone and navigate to this repository and execute the following:
+or alternatively with the provided wrapper script:
 ```shell
-./docker.sh build
-./docker.sh demo
+./result/bin/DiffDetective-Demo
 ```
 
 
@@ -205,3 +225,13 @@ To fix, start the docker daemon as it was probably not running.
 ### Gtk-Message: 00:08:30.171: Failed to load module "colorreload-gtk-module"
 
 This error can be savely ignore. The `colorreload-gtk-module` is used for theming and, hence, is not useful in this scenario.
+
+### error: experimental Nix feature 'nix-command' is disabled; add '--extra-experimental-features nix-command' to enable it
+
+You ran Nix flakes without having enabled it. Either enable it by adding the extra parameters to the call as indicated in the error message, or stick to the non-experimental nix commands as described above (recommended).
+
+### Exception in thread "main" java.nio.file.NoSuchFileException: data/examples/simple_v1.txt
+
+The demo could not find one of this input files.
+This likely happened because you ran the demo from a working directory that is not the top level of this repository in the terminal (i.e, the directory containing this INSTALL.md file).
+To fix, navigate to the root directory of this repository in your terminal and run the demo again.

README.md

@@ -1,6 +1,6 @@
 # DiffDetective-Demo
 
-A small demonstration of [DiffDetective](https://github.com/VariantSync/DiffDetective).
+This is a small demonstration of [DiffDetective](https://github.com/VariantSync/DiffDetective).
 The purpose of this demo is to provide an example of how to use DiffDetective and to serve as a template project for you to clone and adapt as a quickstart for developing with DiffDetective.
 
 There is a screencast available on YouTube, guiding you through the demo's setup with Maven in IntelliJ and how to implement variability-aware differencing and analyses of Git histories:
@@ -10,16 +10,14 @@ There is a screencast available on YouTube, guiding you through the demo's setup
 This demo, also manifests the artifact submission for our paper _Variability-Aware Differencing with DiffDetective_, accepted at the FSE'24 demonstrations track.
 A preprint of the paper is available as part of this repository, [here](Variability-Aware%20Differencing%20with%20DiffDetective.pdf).
 Our application for artifact badges can be found in the [STATUS.md](STATUS.md) file.
+Please note that this submission is _not_ a replication package of an empirical study (e.g., tool evaluation).
+Instead, this repository is a template project with examples for how to use DiffDetective as a library (i.e., a demo).
 
 ## Setup
 
 The demo is a Java Maven project, which includes DiffDetective as a library.
-You may run the demo manually, or by using Nix or Docker.
-The manual setup enables you to use DiffDetective in any of your own Maven projects.
-The Nix and Docker setups just build the demo for you to run it.
 
 Software requirements are documented in the [REQUIREMENTS.md](REQUIREMENTS.md) file (there are no specific hardware requirements).
 Basically, you will have to install Java and Maven, or alternatively Nix or Docker.
 
 Installation instructions are documented in the [INSTALL.md](INSTALL.md) file.
-

REQUIREMENTS.md

@@ -4,41 +4,40 @@ None
 
 ## Software Requirements
 
-> This demo can be run with Docker or Nix. If you intend to use one of them, you may skip to the last section in this document. 
-
 We do not require a certain operating system or prepared environment.
 For downloading this demo, we recommend Git (installing Git is explained in [this article](https://github.com/git-guides/install-git)).
-The setup is tested on Windows 10, WSL2, Manjaro, Ubuntu, NixOS and MacOS Monterey.
+The setup is tested on Windows 10, WSL2, Manjaro, and NixOS.
+
+**Executing the demo consists of two steps**: _building the project_ and _running the demo_.
+Each step has its own software requirements.
+
+
+### Requirements for Building
+
+This demo can be built _either_ manually _or_ using Docker _or_ using Nix.
+You may choose one of these setups.
+If you intend to use this project to develop your own library or application based on DiffDetective, we recommend the manual build.
+
+#### Requirements for Building Manually
 
-### Toolchain
 This demo is a Maven project based on Java 17.
 
 To build the demo, a [Java development toolkit](https://www.oracle.com/java/technologies/downloads/) of version 17 or higher, and [Maven](https://maven.apache.org/) are required.
 
-To run the demo, graphviz should be installed. You may find installation instructions for graphviz [here](https://graphviz.org/download/).
-You may run the demo without graphviz but the demo will print an error to the terminal and DiffDetective cannot compute a layout for visualizing graphs.
-So the GUI may appear differently as in the screencast (see _Expected Output_ section in [INSTALL.md](INSTALL.md)).
-
-### Java Dependencies
 The demo has few dependencies, most of which will be handled automatically by Maven.
 The dependencies are documented in the Maven build file ([pom.xml](pom.xml)).
 The only dependency that must be installed manually is our tool and library DiffDetective, which is also a Java Maven project.
 Installing DiffDetective follows the default maven workflow and is explained on the [DiffDetective website](https://variantsync.github.io/DiffDetective/) and README.
 
-## Virtualization: Docker or Nix
-For easy replication, this demo also comes with a Nix package and a Docker container, which can be used on any system supporting Nix or Docker, respectively.
-The Nix and Docker setup will take care of all requirements and dependencies (including DiffDetective) and will build the demo to a single runnable JAR file.
-_Note_: Nix and Docker are neither required by the demo nor DiffDetective! They only serve to ease the setup for you.
-
-### Docker
+#### Requirements for Building with Docker
 
 How to install Docker depends on your operating system:
 
 - _Windows or Mac_: You can find download and installation instructions [here](https://www.docker.com/get-started).
 - _Linux Distributions_: How to install Docker on your system, depends on your distribution. The chances are high that Docker is part of your distributions package database.
   Docker's [documentation](https://docs.docker.com/engine/install/) contains instructions for common distributions.
 
-### Nix
+#### Requirements for Building with Nix
 
 How to install Nix, also depends on your operating system.
 Head to the [NixOS website](https://nixos.org/download/) and follow the installation instructions for your system.
@@ -49,4 +48,17 @@ Instead, you can use Nix from within Windows Subsystem for Linux (WSL2).
 However, we do not recommend using Nix on Windows, except if you are already familiar with WSL2, Nix, and XServers.
 We recommend using Docker or a manual setup instead.
 Running the Demo from within WSL2 requires an XServer.
-We recommend [VcXsrv](https://sourceforge.net/projects/vcxsrv/).
+We recommend [VcXsrv](https://sourceforge.net/projects/vcxsrv/).
+
+### Requirements for Running
+
+To run the demo, a [Java development toolkit](https://www.oracle.com/java/technologies/downloads/) of version 17 or higher is required.
+
+As an _optional_ dependency, running the demo uses graphviz.
+You may find installation instructions for graphviz [here](https://graphviz.org/download/).
+You may run the demo without graphviz, in which case the demo will print an error to the terminal and DiffDetective cannot compute a layout for visualizing graphs.
+In this case, the GUI may appear differently as in the screencast (see _Expected Output_ section in [INSTALL.md](INSTALL.md)).
+
+> We also provide a nix and docker setup for running the demo, too. However, these setups are fragile because the demo launches a graphical user interface which may cause errors.
+> Hence, you can also run the demo without installing Java or graphviz.
+> We hence recommend to run the demo manually with Java.

build-jar.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+cd "$(dirname "${BASH_SOURCE[0]}")" || exit
+
+if command -v nix-build &>/dev/null
+then
+  echo "Using Nix to build the DiffDetective demo jar."
+  nix-build &&
+  cp -f result/share/java/DiffDetective-Demo.jar . &&
+  chmod u+w DiffDetective-Demo.jar &&
+  echo "The jar has been built successfully. You can find it in $(realpath DiffDetective-Demo.jar)" &&
+  echo "You might want to remove the 'result' link ('rm result') to allow the Nix garbage collector to reclaim some space."
+elif command -v docker &>/dev/null
+then
+  echo "Using Docker to build the DiffDetective demo jar."
+
+  root=0
+  if ! groups | grep -q docker
+  then
+    if [ "$(id -u)" -ne 0 ]
+    then
+      echo >&2 "You don't seem to be able to run Docker as your user. Please start this script as root (e.g., using 'sudo') or ensure you are a member of the docker group."
+      exit 2
+    fi
+  fi
+
+  if ! docker version &>/dev/null
+  then
+    echo >&2 "Docker isn't running. You need to start the docker engine first."
+    echo >&2 "On most Linux distributions you can do so using 'systemctl start docker'."
+    exit 3
+  fi
+
+  docker build . --tag diffdetective-demo:1.0.0 &&
+  docker run --volume "$PWD:/output:rw" diffdetective-demo:1.0.0 /bin/cp /DiffDetective/share/java/DiffDetective-Demo.jar /output
+
+  if [ "$?" -eq 0 ]
+  then
+    echo
+    echo "The jar has been built successfully. You can find it in $(realpath DiffDetective-Demo.jar)"
+    echo "You might want to remove the Docker image ('docker image rm diffdetective-demo:1.0.0')."
+
+    if [ "$(id -u)" -eq 0 ]
+    then
+      echo "You might want to change the owner of the jar ('chown username:group DiffDetective-Demo.jar') because it's current owner is root."
+    fi
+  fi
+else
+  echo "Neither Nix nor Docker are installed. You need to compile the jar for yourselves. See INSTALL.md for instructions."
+fi