java-wrappers - capacities shared by java wrapper scripts
Most Java programs are not run directly, but through small shell scripts that
take care of various things, such as finding a suitable Java environment and
looking for libraries.
To ease the task of the maintainers, they rely on a library providing runtime
detection, library detection and other features. This manual page describes
the common features of all those scripts, and to which point you can configure
them. This is mainly done via environment variables.
java-wrappers understands some environment variables:
- JAVA_CMD
- The java command that will be run. If this variable
is set, it disables all lookup for a java runtime.
- JAVA_BINDIR
- Specifies a directory that will be looked for a java
or a jdb executable (depending on the setting of
JAVA_DEBUGGER). It has precedence over JAVA_HOME but not
over JAVA_CMD.
- JAVA_HOME
- A path to a Java runtime. If this variable is set, all
lookup for a Java runtime is disabled, except that if no java
executable is found in the path, the command java is used.
- JAVA_FLAVOR
- A probably more easy-to-use version of the JAVA_HOME
variable: instead of specifying the full path of the Java runtime, you
name it. List of available flavors can be found in the file
/usr/lib/java-wrappers/jvm-list.sh. See examples below.
- JAVA_DEBUGGER
- If this is set, the wrapper will try to pick up a Java
debugger rather than a Java interpreter. This will fail if the jbd
of the runtime found is a stub.
- JAVA_CLASSPATH
- Additional classpath, will have priority over the one found
by the wrapper.
- JAVA_ARGS
- Additional arguments to the java command. They will
come before all other arguments.
- FORCE_CLASSPATH
- If this variable is set, it will be the only
classpath. You'd better know what you are doing.
- DEBUG_WRAPPER
- This is probably the most important variable; if it set,
the wrapper will print out useful information as it goes by its business,
such as which runtime it did find, and which command is run eventually.
- JAVA_JARPATH
- The path where the wrappers will go looking for jar
archives. If not set, the wrapper will look into the default directory,
/usr/share/java. Warning : the wrapper will not look
anywhere else than in JAVA_JARPATH. Setting it incorrectly will
most probably result in early crashes.
The examples all rely on
rasterizer(1), from the package
libbatik-java, but they really apply to all scripts that use
java-wrappers.
Print out debugging information:
DEBUG_WRAPPER=1 rasterizer
Limit rasterizer's memory to 80 MB:
JAVA_ARGS=-Xmx80m rasterizer
Force rasterizer to run with
kaffe(1):
JAVA_HOME=/usr/lib/kaffe rasterizer
The same, but using
JAVA_BINDIR:
JAVA_BINDIR=/usr/lib/kaffe/bin rasterizer
Force rasterizer to run with
openjdk:
JAVA_FLAVOR=openjdk rasterizer
Debug rasterizer with Sun's debugger, while printing debugging information from
the wrapper:
DEBUG_WRAPPER=1 JAVA_CMD=/usr/lib/jvm/java-6-sun/bin/jdb rasterizer
Care has been taken to make the wrappers bug-free. If that was not the case,
please file a bug report against the
java-wrappers package.
If you wish to submit any problem with a Java executable relying on
java-wrappers, please also submit the output of the command run with
DEBUG_WRAPPER=1. It will save one mail exchange and therefore
potentially reduce the time it takes to fix the bug.
There is currently no documentation about writing a wrapper script save the
comments in
/usr/lib/java-wrappers/java-wrappers.sh. If you have to
write one, we suggest you base yourself upon, for instance, the
rasterizer wrapper script, or any other one (just pick up any direct
reverse dependency of
java-wrappers and look for scripts).
java(1),
jdb(1)
/usr/lib/java-wrappers/java-wrappers.sh
java-wrappers and its documentation were written by Vincent Fourmond
<
[email protected]>