depot/doc/languages-frameworks/java.section.md
Luke Granger-Brown 57725ef3ec Squashed 'third_party/nixpkgs/' content from commit 76612b17c0ce
git-subtree-dir: third_party/nixpkgs
git-subtree-split: 76612b17c0ce71689921ca12d9ffdc9c23ce40b2
2024-11-10 23:59:47 +00:00

3.3 KiB

Java

Ant-based Java packages are typically built from source as follows:

stdenv.mkDerivation {
  pname = "...";
  version = "...";

  src = fetchurl { /* ... */ };

  nativeBuildInputs = [
    ant
    jdk
    stripJavaArchivesHook # removes timestamp metadata from jar files
  ];

  buildPhase = ''
    runHook preBuild
    ant # build the project using ant
    runHook postBuild
  '';

  installPhase = ''
    runHook preInstall

    # copy generated jar file(s) to an appropriate location in $out
    install -Dm644 build/foo.jar $out/share/java/foo.jar

    runHook postInstall
  '';
}

Note that jdk is an alias for the OpenJDK (self-built where available, or pre-built via Zulu).

Also note that not using stripJavaArchivesHook will likely cause the generated .jar files to be non-deterministic, which is not optimal. Using it, however, does not always guarantee reproducibility.

JAR files that are intended to be used by other packages should be installed in $out/share/java. JDKs have a stdenv setup hook that add any JARs in the share/java directories of the build inputs to the CLASSPATH environment variable. For instance, if the package libfoo installs a JAR named foo.jar in its share/java directory, and another package declares the attribute

{
  buildInputs = [ libfoo ];
  nativeBuildInputs = [ jdk ];
}

then CLASSPATH will be set to /nix/store/...-libfoo/share/java/foo.jar.

Private JARs should be installed in a location like $out/share/package-name.

If your Java package provides a program, you need to generate a wrapper script to run it using a JRE. You can use makeWrapper for this:

{
  nativeBuildInputs = [ makeWrapper ];

  installPhase = ''
    mkdir -p $out/bin
    makeWrapper ${jre}/bin/java $out/bin/foo \
      --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
  '';
}

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 jre package is the full JDK. When building a minimal system/image, you can override the modules parameter on jre_minimal to build a JRE with only the modules relevant for you:

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
  <...>

You can also specify what JDK your JRE should be based on, for example selecting a 'headless' build to avoid including a link to GTK+:

{
  my_jre = pkgs.jre_minimal.override {
    jdk = jdk11_headless;
  };
}

Note all JDKs passthru home, so if your application requires environment variables like JAVA_HOME being set, that can be done in a generic fashion with the --set argument of makeWrapper:

--set JAVA_HOME ${jdk.home}

It is possible to use a different Java compiler than javac from the OpenJDK. For instance, to use the GNU Java Compiler:

{
  nativeBuildInputs = [ gcj ant ];
}

Here, Ant will automatically use gij (the GNU Java Runtime) instead of the OpenJRE.