Merge pull request #105230 from Mic92/java-doc
doc/java: convert to markdown
This commit is contained in:
Ryan Mulligan
GitHub
commit
795f75f21d
@ -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" />
|
||||
|
||||
91
doc/languages-frameworks/java.section.md
Normal file
91
doc/languages-frameworks/java.section.md
Normal file
@ -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.
|
||||
@ -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>
|
||||
Loading…
Reference in New Issue
Block a user