Release 2.3.0

.editorconfig

@@ -0,0 +1,14 @@
+root = true
+
+# We let Git handle end_of_line such that this setting is effectively platform
+# dependent but still normalized in the Git store. See .gitattributes
+
+[*]
+charset = utf-8
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.nix]
+indent_size = 2

.github/workflows/maven.yml

@@ -16,17 +16,14 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Install Nix with cached packages
-      uses: rikhuijzer/cache-install@v.1.1.3
-      with:
-        key: nix-${{ hashFiles('.github/workflows/maven.yml', 'default.nix', 'nix/**', 'pom.xml', 'local-maven-repo') }}
-        nix_file: nix/github-workflow-dependencies.nix
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v31
+    # The dependencies could be cached if necessary. See PR #156 and da11a13c1451f5a52672fe494ac6e20116346865 for additional information.
     - name: Build
       run: nix-build
     - name: Upload Javadoc artifact
       if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
-      uses: actions/upload-pages-artifact@v1
+      uses: actions/upload-pages-artifact@v3
       with:
         path: result/share/github-pages/DiffDetective
 
@@ -50,7 +47,7 @@ jobs:
     steps:
     - name: Publish Javadoc to Github Pages
       id: deployment
-      uses: actions/deploy-pages@v1
+      uses: actions/deploy-pages@v4
 
     # Kill in progress deployments because only the newest version is relevant
     # and concurrent deployments cause CI failures.

README.md

@@ -49,11 +49,11 @@ To add DiffDetective as a dependency to your own project, add the following snip
 <dependency>
     <groupId>org.variantsync</groupId>
     <artifactId>DiffDetective</artifactId>
-    <version>2.2.0</version>
+    <version>2.3.0</version>
 </dependency>
 ```
 
-If you prefer to just use a jar file, you can find a jar file with all dependencies at `DiffDetective/target/diffdetective-2.2.0-jar-with-dependencies.jar` (again, the version number might be different).
+If you prefer to just use a jar file, you can find a jar file with all dependencies at `DiffDetective/target/diffdetective-2.3.0-jar-with-dependencies.jar` (again, the version number might be different).
 You can (re-)produce this jar file by either running `mvn package` or `mvn install` within you local clone of DiffDetective.
 
 > Disclaimer: Setup tested with maven version 3.6.3.
@@ -68,7 +68,7 @@ nix build # Flake version
 ```
 In case you are using Nix Flakes, you can skip cloning the repository as usual: `nix build github:VariantSync/DiffDetective#.`
 
-Afterward, the [result](result) symlink points to the [Javadoc](result/share/github-pages/DiffDetective/docs/javadoc/index.html), the [DiffDetective jar](result/share/java/DiffDetective/DiffDetective.jar) and a simple [script](result/bin/DiffDetective) for executing a DiffDetective main class provided as argument (e.g., evaluations used in previous research, see below under 'Publications').
+Afterward, the [result](result) symlink points to the [Javadoc](result/share/github-pages/DiffDetective/docs/javadoc/index.html), a [DiffDetective jar for use as a library](result/share/java/DiffDetective.jar), a [self contained DiffDetective jar with all dependencies included](result/share/java/DiffDetective/DiffDetective-jar-with-dependencies.jar) and a simple [script](result/bin/DiffDetective) for executing a DiffDetective main class provided as argument (e.g., evaluations used in previous research, see below under 'Publications').
 
 
 ## How to Get Started

default.nix

@@ -3,65 +3,111 @@
   system ? builtins.currentSystem,
   pkgs ?
     import sources.nixpkgs {
-      overlays = [];
+      overlays = [
+        (final: previous: {
+          defaultGemConfig = previous.defaultGemConfig // {
+            jekyll-github-metadata = attrs: {
+              dontBuild = false;
+              patches = [
+                (final.fetchpatch {
+                  url = "https://github.com/jekyll/github-metadata/commit/17cc5af5e1fd95d98d43676610cc8a47969350ab.patch";
+                  hash = "sha256-dUqvnYsjfG5xQIYS48B3xz0GLVYo2BrDAnYUafmDFKw=";
+                  relative = "lib";
+                  stripLen = 1;
+                  extraPrefix = "lib/jekyll-github-metadata/";
+                })
+              ];
+            };
+          };
+        })
+      ];
       config = {};
       inherit system;
     },
   doCheck ? true,
   buildGitHubPages ? true,
+  dependenciesHash ? "sha256-OdagSk6jYCkkw/kPoOJlma9yEK7hMBcNkuxE6qt0ra8=",
 }:
 pkgs.stdenvNoCC.mkDerivation rec {
   pname = "DiffDetective";
   # The single source of truth for the version number is stored in `pom.xml`.
   # Hence, this XML file needs to be parsed to extract the current version.
   version = pkgs.lib.removeSuffix "\n" (pkgs.lib.readFile
-    (pkgs.runCommandLocal "DiffDetective-version" {}
-      "${pkgs.xq-xml}/bin/xq -x '/project/version' ${./pom.xml} > $out"));
+    (pkgs.runCommandLocal "DiffDetective-version" {
+      nativeBuildInputs = [pkgs.xq-xml];
+    } "xq -x '/project/version' ${./pom.xml} > $out"));
   src = with pkgs.lib.fileset;
     toSource {
       root = ./.;
       fileset = gitTracked ./.;
     };
 
-  nativeBuildInputs = with pkgs; [
-    maven
-    makeWrapper
-    graphviz
-  ] ++ pkgs.lib.optional buildGitHubPages (ruby.withPackages (pkgs: with pkgs; [
-    github-pages
-    jekyll-theme-cayman
+  nativeBuildInputs = [
+    pkgs.maven
+    pkgs.makeWrapper
+  ] ++ pkgs.lib.optional buildGitHubPages (pkgs.ruby.withPackages (rubyPkgs: [
+    rubyPkgs.github-pages
+    rubyPkgs.jekyll-theme-cayman
   ]));
 
+  nativeCheckInputs = [
+    pkgs.graphviz
+  ];
+
+  # Maven needs to download necessary dependencies which is impure because it
+  # requires network access. Hence, we download all dependencies as a
+  # fixed-output derivation. This also serves as a nice cache.
+  #
+  # We use the hash of the input files to invalidate the maven cache whenever
+  # the input files change. This is purely for easing maintenance. In case a
+  # maintainer forgets (or simply doesn't know) to change the output hash to
+  # force a rebuild (and obtain the new, correct hash) this usually (without
+  # this naming hack) result in use of a stall cash, essentially behaving like
+  # an unreproducable derivation where a second build results in a different
+  # output. By changing the name of the fixed output derivation whenever
+  # `mavenRepoSrc` changes, we prevent this stall cache as the resulting store
+  # path will never exist (except when the cache is valid).
+  mavenRepoSrc = pkgs.lib.sourceByRegex ./. ["^pom.xml$" "^local-maven-repo(/.*)?$"];
+  mavenRepoSrcName = with pkgs.lib; last (splitString "/" mavenRepoSrc.outPath);
   mavenRepo = pkgs.stdenv.mkDerivation {
-    pname = "${pname}-mavenRepo";
+    pname = "${pname}-mavenRepo-${mavenRepoSrcName}";
     inherit version;
-    src = pkgs.lib.sourceByRegex ./. ["^pom.xml$" "^local-maven-repo(/.*)?$"];
+    src = mavenRepoSrc;
 
-    nativeBuildInputs = with pkgs; [maven];
+    nativeBuildInputs = [pkgs.maven];
 
     buildPhase = ''
+      runHook preBuild
+
       mvn org.apache.maven.plugins:maven-dependency-plugin:3.6.0:go-offline -Dmaven.repo.local="$out"
+
+      runHook postBuild
     '';
 
     # keep only *.{pom,jar,sha1,nbm} and delete all ephemeral files with lastModified timestamps inside
     installPhase = ''
+      runHook preInstall
+
       find "$out" -type f \
-        \( -name \*.lastUpdated -or \
-           -name resolver-status.properties -or \
-           -name _remote.repositories \) \
+        \( -not \( -name "*.pom" -o -name "*.jar" -o -name "*.sha1" -o -name "*.nbm" \) \
+            -o -name "maven-metadata*" \) \
         -delete
+
+      runHook postInstall
     '';
 
     dontFixup = true;
     dontConfigure = true;
     outputHashAlgo = "sha256";
     outputHashMode = "recursive";
-    outputHash = "sha256-TYZP4XhM3ExLNC3H/QLch6LMVQxbR1LECwubMZn+RXY=";
+    outputHash = dependenciesHash;
   };
 
-  jre-minimal = pkgs.callPackage (import "${sources.nixpkgs}/pkgs/development/compilers/openjdk/jre.nix") {
-    modules = ["java.base" "java.desktop"];
-  };
+  # - `out` contains jars, an executable wrapper and optionally documentation
+  #   (see `buildGitHubPages`)
+  # - `maven` contains a local maven repository with DiffDetective and all its
+  #   build-time and run-time dependencies.
+  outputs = ["out" "maven"];
 
   buildPhase = ''
     runHook preBuild
@@ -76,7 +122,8 @@ pkgs.stdenvNoCC.mkDerivation rec {
       if buildGitHubPages
       then ''
         mvn javadoc:javadoc
-        JEKYLL_ENV=production PAGES_REPO_NWO=VariantSync/DiffDetective JEKYLL_BUILD_REVISION= github-pages build
+        mv target/reports/apidocs docs/javadoc
+        JEKYLL_ENV=production PAGES_REPO_NWO=VariantSync/DiffDetective JEKYLL_BUILD_REVISION= PAGES_DISABLE_NETWORK=1 github-pages build
         rm -rf _site/target
       ''
       else ""
@@ -88,30 +135,46 @@ pkgs.stdenvNoCC.mkDerivation rec {
 
   inherit doCheck;
   checkPhase = ''
-    runHook postTest
+    runHook preTest
 
     mvn --offline -Dmaven.repo.local="$mavenRepo" test
 
     runHook postTest
   '';
 
   installPhase = ''
-    runHook postInstall
+    runHook preInstall
 
-    local jar="$out/share/java/DiffDetective/DiffDetective.jar"
-    install -Dm644 "target/diffdetective-${version}-jar-with-dependencies.jar" "$jar"
-    makeWrapper "${jre-minimal}/bin/java" "$out/bin/DiffDetective" --add-flags "-cp \"$jar\"" \
-      --prefix PATH : "${pkgs.graphviz}/bin"
+    # install jars in "$out"
+    install -Dm644 "target/diffdetective-$version.jar" "$out/share/java/DiffDetective.jar"
+    local jar="$out/share/java/DiffDetective/DiffDetective-jar-with-dependencies.jar"
+    install -Dm644 "target/diffdetective-$version-jar-with-dependencies.jar" "$jar"
+    makeWrapper \
+      "${pkgs.jdk}/bin/java" "$out/bin/DiffDetective" \
+      --add-flags "-cp \"$jar\"" \
+      --prefix PATH : "${pkgs.lib.makeBinPath [pkgs.graphviz]}"
 
     ${
       if buildGitHubPages
       then ''
+        # install documentation in "$out"
         mkdir "$out/share/github-pages"
         cp -r _site "$out/share/github-pages/DiffDetective"
       ''
       else ""
     }
 
+    # install DiffDetective in "$maven" by creating a copy of "$mavenRepo" as base
+    cp -r "$mavenRepo" "$maven"
+    chmod u+w -R "$maven"
+    mvn --offline -Dmaven.repo.local="$maven" -Dmaven.test.skip=true install
+
+    # keep only *.{pom,jar,sha1,nbm} and delete all ephemeral files with lastModified timestamps inside
+    find "$maven" -type f \
+      \( -not \( -name "*.pom" -o -name "*.jar" -o -name "*.sha1" -o -name "*.nbm" \) \
+          -o -name "maven-metadata*" \) \
+      -delete
+
     runHook postInstall
   '';
 

docker/entrypoint.sh

@@ -1,9 +1,9 @@
 #!/bin/sh
 if [ "$(id -u)" = "0" ]; then
-  # running on a developer laptop as root
-  fix-perms -r -u user -g user /home/user
-  exec gosu user "$@"
+    # running on a developer laptop as root
+    fix-perms -r -u user -g user /home/user
+    exec gosu user "$@"
 else
-  # running in production as a user
-  exec "$@"
-fi
+    # running in production as a user
+    exec "$@"
+fi

docker/fix-perms.sh

@@ -1,12 +1,12 @@
 # update the uid
 if [ -n "$opt_u" ]; then
-  OLD_UID=$(getent passwd "${opt_u}" | cut -f3 -d:)
-  NEW_UID=$(stat -c "%u" "$1")
-  if [ "$OLD_UID" != "$NEW_UID" ]; then
-    echo "Changing UID of $opt_u from $OLD_UID to $NEW_UID"
-    usermod -u "$NEW_UID" -o "$opt_u"
-    if [ -n "$opt_r" ]; then
-      find / -xdev -user "$OLD_UID" -exec chown -h "$opt_u" {} \;
+    OLD_UID=$(getent passwd "${opt_u}" | cut -f3 -d:)
+    NEW_UID=$(stat -c "%u" "$1")
+    if [ "$OLD_UID" != "$NEW_UID" ]; then
+        echo "Changing UID of $opt_u from $OLD_UID to $NEW_UID"
+        usermod -u "$NEW_UID" -o "$opt_u"
+        if [ -n "$opt_r" ]; then
+            find / -xdev -user "$OLD_UID" -exec chown -h "$opt_u" {} \;
+        fi
     fi
-  fi
-fi
+fi