From a91a5b5f3a3ff9d967544a7335acc82bd084c140 Mon Sep 17 00:00:00 2001
From: Thibault Gagnaux <tgagnaux@gmail.com>
Date: Mon, 20 May 2024 16:49:20 +0200
Subject: [PATCH] doc/maven: document maven offline build usage

---
 doc/languages-frameworks/maven.section.md | 69 ++++++++++++++++++++---
 1 file changed, 61 insertions(+), 8 deletions(-)

diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md
index e2f493c603069..69315d0556a44 100644
--- a/doc/languages-frameworks/maven.section.md
+++ b/doc/languages-frameworks/maven.section.md
@@ -51,12 +51,26 @@ After setting `maven.buildMavenPackage`, we then do standard Java `.jar` install
 
 ### Overriding Maven package attributes {#maven-overriding-package-attributes}
 
-The `buildMavenPackage` function has a `overrideMavenAttrs` method that can be
-used to override the attributes of a maven package. In the following example we
-want to use an older version of jd-cli and disable some flaky test:
+```
+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 {
+jd-cli.overrideMavenAttrs (old: rec {
   version = "1.2.0";
   src = fetchFromGitHub {
     owner = old.src.owner;
@@ -66,18 +80,57 @@ jd-cli.overrideMavenAttrs(old: rec {
     hash = "sha256-US7j6tQ6mh1libeHnQdFxPGoxHzbZHqehWSgCYynKx8=";
   };
 
-  # tests can be disabled by prefixing it with !
-  # see the docs for more info: https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html#Multiple_Formats_in_One
+  # 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"
+    "-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}