buildMavenPackage: Add `overrideMavenAttrs` function and `buildOffline` documentation (#313152)

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}

### `overrideMavenAttrs` 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.

  "maven-buildmavenpackage": [

    "index.html#maven-buildmavenpackage"

  ],

  "maven-overriding-package-attributes": [

    "index.html#maven-overriding-package-attributes"

  ],

  "maven-offline-build": [

    "index.html#maven-offline-build"

  ],

  "stable-maven-plugins": [

    "index.html#stable-maven-plugins"

  ],

  makeWrapper,

  stdenvNoCC,

}:

stdenvNoCC.mkDerivation (finalAttrs: {

  pname = "maven";

  version = "3.9.9";

    runHook postInstall

  '';

  passthru = {

  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

    {

      buildMaven = callPackage ./build-maven.nix {

        maven = finalAttrs.finalPackage;

      };

    buildMavenPackage = callPackage ./build-maven-package.nix {

      buildMavenPackage = makeOverridableMavenPackage (

        callPackage ./build-maven-package.nix {

          maven = finalAttrs.finalPackage;

    };

        }

      );

    };

  meta = {

    '';

    license = lib.licenses.asl20;

    mainProgram = "mvn";

    maintainers = [ ] ++ lib.teams.java.members;

    maintainers = with lib.maintainers; [ tricktron ] ++ lib.teams.java.members;

    inherit (jdk_headless.meta) platforms;

  };

})