openjdk: add derivation to generate bespoke minimal JRE's

Co-Authored-By: Robert Hensing <robert@roberthensing.nl>

1 files changed, 16 insertions, 2 deletions

diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
index bf0fc4883922..881d492b5bff 100644
--- a/doc/languages-frameworks/java.xml
+++ b/doc/languages-frameworks/java.xml
@@ -32,7 +32,7 @@ nativeBuildInputs = [ jdk ];
  </para>
 
  <para>
-  If your Java package provides a program, you need to generate a wrapper script to run it using the OpenJRE. You can use <literal>makeWrapper</literal> for this:
+  If your Java package provides a program, you need to generate a wrapper script to run it using a JRE. You can use <literal>makeWrapper</literal> for this:
 <programlisting>
 nativeBuildInputs = [ makeWrapper ];
 
@@ -43,7 +43,21 @@ installPhase =
       --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
   '';
 </programlisting>
-  Note the use of <literal>jre</literal>, which is the part of the OpenJDK package that contains the Java Runtime Environment. By using <literal>${jre}/bin/java</literal> instead of <literal>${jdk}/bin/java</literal>, you prevent your package from depending on the JDK at runtime.
+Since the introduction of the Java Platform Module System in Java 9, Java distributions typically no longer ship with a general-purpose JRE: instead, they allow generating a JRE with only the modules required for your application(s). Because we can't predict what modules will be needed on a general-purpose system, the default <package>jre</package> package is the full JDK. When building a minimal system/image, you can override the <literal>modules</literal> parameter on <literal>jre_minimal</literal> to build a JRE with only the modules relevant for you:
+<programlisting>
+let
+  my_jre = pkgs.jre_minimal.override {
+    modules = [
+      # The modules used by 'something' and 'other' combined:
+      "java.base"
+      "java.logging"
+    ];
+  };
+  something = (pkgs.something.override { jre = my_jre; });
+  other = (pkgs.other.override { jre = my_jre; });
+in
+  ...
+</programlisting>
  </para>
 
  <para>