buildMavenPackage: Add overrideMavenAttrs function and buildOffline documentation

doc/languages-frameworks/maven.section.md

@@ -49,6 +49,89 @@ This package calls `maven.buildMavenPackage` to do its work. The primary differe
 After setting `maven.buildMavenPackage`, we then do standard Java `.jar` installation by saving the `.jar` to `$out/share/java` and then making a wrapper which allows executing that file; see [](#sec-language-java) for additional generic information about packaging Java applications.
 :::
 
+### Overriding Maven package attributes {#maven-overriding-package-attributes}
+
+```
+overrideMavenAttrs :: (AttrSet -> Derivation) | ((AttrSet -> Attrset) -> Derivation) -> Derivation
+```
+
+The output of `buildMavenPackage` has an `overrideMavenAttrs` attribute, which is a function that takes either
+- any subset of the attributes that can be passed to `buildMavenPackage`
+
+  or
+- a function that takes the argument passed to the previous invocation of `buildMavenPackage` (conventionally called `old`) and returns an attribute set that can be passed to `buildMavenPackage`
+
+and returns a derivation that builds a Maven package based on the old and new arguments merged.
+
+This is similar to [](#sec-pkg-overrideAttrs), but notably does not allow accessing the final value of the argument to `buildMavenPackage`.
+
+:::{.example}
+
+Use `overrideMavenAttrs` to build `jd-cli` version 1.2.0 and disable some flaky test:
+
+```nix
+jd-cli.overrideMavenAttrs (old: rec {
+  version = "1.2.0";
+  src = fetchFromGitHub {
+    owner = old.src.owner;
+    repo = old.src.repo;
+    rev = "${old.pname}-${version}";
+    # old source hash of 1.2.0 version
+    hash = "sha256-US7j6tQ6mh1libeHnQdFxPGoxHzbZHqehWSgCYynKx8=";
+  };
+
+  # tests can be disabled by prefixing it with `!`
+  # see Maven documentation for more details:
+  # https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html#Multiple_Formats_in_One
+  mvnParameters = lib.escapeShellArgs [
+    "-Dsurefire.failIfNoSpecifiedTests=false"
+    "-Dtest=!JavaDecompilerTest#basicTest,!JavaDecompilerTest#patternMatchingTest"
+  ];
+
+  # old mvnHash of 1.2.0 maven dependencies
+  mvnHash = "sha256-N9XC1pg6Y4sUiBWIQUf16QSXCuiAPpXEHGlgApviF4I=";
+});
+```
+:::
+
+### Offline build {#maven-offline-build}
+
+By default, `buildMavenPackage` does the following:
+
+1. Run `mvn package -Dmaven.repo.local=$out/.m2 ${mvnParameters}` in the
+   `fetchedMavenDeps` [fixed-output derivation](https://nixos.org/manual/nix/stable/glossary.html#gloss-fixed-output-derivation).
+2. Run `mvn package -o -nsu "-Dmaven.repo.local=$mvnDeps/.m2"
+   ${mvnParameters}` again in the main derivation.
+
+As a result, tests are run twice.
+This also means that a failing test will trigger a new attempt to realise the fixed-output derivation, which in turn downloads all dependencies again.
+For bigger Maven projects, this might lead to a long feedback cycle. 
+
+Use `buildOffline = true` to change the behaviour of `buildMavenPackage to the following:
+1. Run `mvn de.qaware.maven:go-offline-maven-plugin:1.2.8:resolve-dependencies
+   -Dmaven.repo.local=$out/.m2 ${mvnDepsParameters}` in the fixed-output derivation.
+2. Run `mvn package -o -nsu "-Dmaven.repo.local=$mvnDeps/.m2"
+   ${mvnParameters}` in the main derivation.
+
+As a result, all dependencies are downloaded in step 1 and the tests are executed in step 2.
+A failing test only triggers a rebuild of step 2 as it can reuse the dependencies of step 1 because they have not changed.
+
+::: {.warning}
+Test dependencies are not downloaded in step 1 and are therefore missing in
+step 2 which will most probably fail the build. The `go-offline` plugin cannot
+handle these so-called [dynamic dependencies](https://github.com/qaware/go-offline-maven-plugin?tab=readme-ov-file#dynamic-dependencies).
+In that case you must add these dynamic dependencies manually with:
+```nix
+maven.buildMavenPackage rec {
+  manualMvnArtifacts = [
+    # add dynamic test dependencies here
+    "org.apache.maven.surefire:surefire-junit-platform:3.1.2"
+    "org.junit.platform:junit-platform-launcher:1.10.0"
+  ];
+};
+```
+:::
+
 ### Stable Maven plugins {#stable-maven-plugins}
 
 Maven defines default versions for its core plugins, e.g. `maven-compiler-plugin`. If your project does not override these versions, an upgrade of Maven will change the version of the used plugins, and therefore the derivation and hash.

nixos/modules/services/desktops/espanso.nix

@@ -6,19 +6,25 @@ in {
   meta = { maintainers = with lib.maintainers; [ numkem ]; };
 
   options = {
-    services.espanso = { enable = options.mkEnableOption "Espanso"; };
+    services.espanso = {
+      enable = mkEnableOption "Espanso";
+      package = mkPackageOption pkgs "espanso" {
+        example = "pkgs.espanso-wayland";
+      };
+    };
   };
 
   config = mkIf cfg.enable {
+    services.espanso.package = mkIf cfg.wayland pkgs.espanso-wayland;
     systemd.user.services.espanso = {
       description = "Espanso daemon";
       serviceConfig = {
-        ExecStart = "${pkgs.espanso}/bin/espanso daemon";
+        ExecStart = "${lib.getExe cfg.package} daemon";
         Restart = "on-failure";
       };
       wantedBy = [ "default.target" ];
     };
 
-    environment.systemPackages = [ pkgs.espanso ];
+    environment.systemPackages = [ cfg.package ];
   };
 }

pkgs/development/tools/build-managers/apache-maven/default.nix

@@ -35,9 +35,23 @@ stdenvNoCC.mkDerivation (finalAttrs: {
     runHook postInstall
   '';
 
-  passthru.buildMavenPackage = callPackage ./build-package.nix {
-    maven = finalAttrs.finalPackage;
-  };
+  passthru =
+    let
+      makeOverridableMavenPackage = mavenRecipe: mavenArgs:
+        let
+          drv = mavenRecipe mavenArgs;
+          overrideWith = newArgs: mavenArgs //
+            (if lib.isFunction newArgs then newArgs mavenArgs else newArgs);
+        in
+          drv // {
+            overrideMavenAttrs = newArgs: makeOverridableMavenPackage mavenRecipe (overrideWith newArgs);
+        };
+    in
+    {
+      buildMavenPackage = makeOverridableMavenPackage (callPackage ./build-package.nix {
+        maven = finalAttrs.finalPackage;
+      });
+    };
 
   meta = with lib; {
     mainProgram = "mvn";