diff options
author | Ryan Mulligan <ryan@ryantm.com> | 2020-11-30 21:57:35 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2020-11-30 21:57:35 -0800 |
commit | 795f75f21deffcb58b63795af1d12af51c4ee481 (patch) | |
tree | 858725d263823669f1773b2d888caed9a266106a /doc/languages-frameworks | |
parent | 6c407c7077f92b8fc9258389af4cf52ca9a79378 (diff) | |
parent | 762e414d6af73e3b68afd40179d605e62e24d494 (diff) | |
download | nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar.gz nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar.bz2 nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar.lz nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar.xz nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.tar.zst nixpkgs-795f75f21deffcb58b63795af1d12af51c4ee481.zip |
Merge pull request #105230 from Mic92/java-doc
doc/java: convert to markdown
Diffstat (limited to 'doc/languages-frameworks')
-rw-r--r-- | doc/languages-frameworks/index.xml | 2 | ||||
-rw-r--r-- | doc/languages-frameworks/java.section.md | 91 | ||||
-rw-r--r-- | doc/languages-frameworks/java.xml | 77 |
3 files changed, 92 insertions, 78 deletions
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml index 65fb2e877f7..c302b67cfd5 100644 --- a/doc/languages-frameworks/index.xml +++ b/doc/languages-frameworks/index.xml @@ -17,7 +17,7 @@ <xi:include href="haskell.section.xml" /> <xi:include href="idris.section.xml" /> <xi:include href="ios.section.xml" /> - <xi:include href="java.xml" /> + <xi:include href="java.section.xml" /> <xi:include href="lua.section.xml" /> <xi:include href="maven.section.xml" /> <xi:include href="node.section.xml" /> diff --git a/doc/languages-frameworks/java.section.md b/doc/languages-frameworks/java.section.md new file mode 100644 index 00000000000..77919d43f74 --- /dev/null +++ b/doc/languages-frameworks/java.section.md @@ -0,0 +1,91 @@ +# Java {#sec-language-java} + +Ant-based Java packages are typically built from source as follows: + +```nix +stdenv.mkDerivation { + name = "..."; + src = fetchurl { ... }; + + nativeBuildInputs = [ jdk ant ]; + + buildPhase = "ant"; +} +``` + +Note that `jdk` is an alias for the OpenJDK (self-built where available, +or pre-built via Zulu). Platforms with OpenJDK not (yet) in Nixpkgs +(`Aarch32`, `Aarch64`) point to the (unfree) `oraclejdk`. + +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 + +```nix +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: + +```nix +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: + +```nix +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 + ... +``` + +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`: + +```bash +--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: + +```nix +nativeBuildInputs = [ gcj ant ]; +``` + +Here, Ant will automatically use `gij` (the GNU Java Runtime) instead of +the OpenJRE. diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml deleted file mode 100644 index 881d492b5bf..00000000000 --- a/doc/languages-frameworks/java.xml +++ /dev/null @@ -1,77 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="sec-language-java"> - <title>Java</title> - - <para> - Ant-based Java packages are typically built from source as follows: -<programlisting> -stdenv.mkDerivation { - name = "..."; - src = fetchurl { ... }; - - nativeBuildInputs = [ jdk ant ]; - - buildPhase = "ant"; -} -</programlisting> - Note that <varname>jdk</varname> is an alias for the OpenJDK (self-built where available, or pre-built via Zulu). Platforms with OpenJDK not (yet) in Nixpkgs (<literal>Aarch32</literal>, <literal>Aarch64</literal>) point to the (unfree) <literal>oraclejdk</literal>. - </para> - - <para> - JAR files that are intended to be used by other packages should be installed in <filename>$out/share/java</filename>. JDKs have a stdenv setup hook that add any JARs in the <filename>share/java</filename> directories of the build inputs to the <envar>CLASSPATH</envar> environment variable. For instance, if the package <literal>libfoo</literal> installs a JAR named <filename>foo.jar</filename> in its <filename>share/java</filename> directory, and another package declares the attribute -<programlisting> -buildInputs = [ libfoo ]; -nativeBuildInputs = [ jdk ]; -</programlisting> - then <envar>CLASSPATH</envar> will be set to <filename>/nix/store/...-libfoo/share/java/foo.jar</filename>. - </para> - - <para> - Private JARs should be installed in a location like <filename>$out/share/<replaceable>package-name</replaceable></filename>. - </para> - - <para> - 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 ]; - -installPhase = - '' - mkdir -p $out/bin - makeWrapper ${jre}/bin/java $out/bin/foo \ - --add-flags "-cp $out/share/java/foo.jar org.foo.Main" - ''; -</programlisting> -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> - Note all JDKs passthru <literal>home</literal>, so if your application requires environment variables like <envar>JAVA_HOME</envar> being set, that can be done in a generic fashion with the <literal>--set</literal> argument of <literal>makeWrapper</literal>: -<programlisting> ---set JAVA_HOME ${jdk.home} -</programlisting> - </para> - - <para> - It is possible to use a different Java compiler than <command>javac</command> from the OpenJDK. For instance, to use the GNU Java Compiler: -<programlisting> -nativeBuildInputs = [ gcj ant ]; -</programlisting> - Here, Ant will automatically use <command>gij</command> (the GNU Java Runtime) instead of the OpenJRE. - </para> -</section> |