Moving the wrappers.sh stuff to java-common + written its user documentation

2 files changed, 316 insertions, 0 deletions

diff --git a/wrappers/java-wrappers.7 b/wrappers/java-wrappers.7
new file mode 100644
index 0000000..25a850b
--- /dev/null
+++ b/wrappers/java-wrappers.7
@@ -0,0 +1,122 @@
+\" Man page documenting the java-wrappers
+\"
+\" Copyright 2008 by Vincent Fourmond
+\"
+\" This documentation is free software; you can redistribute it and/or modify
+\" it under the terms of the GNU General Public License as published by
+\" the Free Software Foundation; either version 2 of the License, or
+\" (at your option) any later version.
+
+\" This package is distributed in the hope that it will be useful,
+\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+\" GNU General Public License for more details.
+
+\" You should have received a copy of the GNU General Public License
+\" along with this program; if not, write to the Free Software
+\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+.TH JAVA-WRAPPERS 7 "2008-01-05" "Version 0.27" "Java wrappers"
+
+.SH NAME
+.B java-wrappers 
+\- capacities shared by java wrapper scripts
+
+.SH DESCRIPTION
+
+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. 
+
+.SH ENVIRONMENT VARIABLES
+
+.B java-wrappers 
+understands some environment variables:
+
+.TP
+.B JAVA_CMD 
+The 
+.I java
+command that will be run. If this variable is set, it disables all
+lookup for a java runtime.
+
+.TP
+.B 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 
+.I java
+executable is found in the path, the command
+.I java
+is used.
+
+.TP
+.B 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 
+.I jbd
+of the runtime found is a stub.
+
+.TP
+.B JAVA_CLASSPATH
+Additional classpath, will have priority over the one found by the
+wrapper. 
+
+.TP
+.B JAVA_ARGS
+Additional arguments to the 
+.I java
+command. They will come before all other arguments.
+
+.TP
+.B FORCE_CLASSPATH
+If this variable is set, it will be 
+.B the only classpath\fR.
+You'd better know what you are doing.
+
+.TP
+.B 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.
+
+.SH EXAMPLES
+
+The examples all rely on 
+.BR rasterizer (1),
+but they really apply to all scripts that use java-wrappers.
+
+Print out debugging information:
+
+.I DEBUG_WRAPPER=1 rasterizer
+
+Limit rasterizer's memory to 80 MB:
+
+.I JAVA_ARGS=-Xmx80m rasterizer
+
+Force rasterizer to run with 
+.BR kaffe (1):
+
+.I JAVA_HOME=/usr/lib/kaffe rasterizer
+
+Debug rasterizer with Sun's debugger, while printing debugging
+information from the wrapper:
+
+.I DEBUG_WRAPPER=1 JAVA_CMD=/usr/lib/jvm/java-6-sun/bin/jdb rasterizer
+
+.SH SEE ALSO
+
+.BR java (1),
+.BR jdb (1)
+
+.I /usr/lib/java/wrappers.sh
+
+.SH AUTHOR
+
+.B java-wrappers
+and its documentation were written by 
+Vincent Fourmond <fourmond@debian.org>
diff --git a/wrappers/wrappers.sh b/wrappers/wrappers.sh
new file mode 100644
index 0000000..faa2152
--- /dev/null
+++ b/wrappers/wrappers.sh
@@ -0,0 +1,194 @@
+# wrappers.sh: various functions to be used by Java script wrappers
+# Copyright 2008 by Vincent Fourmond <fourmond@debian.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+# Some initializations:
+[ "$DESTDIR" ] || DESTDIR=
+[ "$JAVA_CLASSPATH" ] || JAVA_CLASSPATH=
+
+
+# Display a debugging message
+java_debug() {
+    if [ "$DEBUG_WRAPPER" ]; then
+	echo "[debug] $0: $@" >&2;
+    fi
+}
+
+# Displays a warning
+java_warning() {
+    echo "[warning] $0: $@" >&2;
+}
+
+# Exit with an error message
+java_fail() {
+    echo "[error] $0: $@" >&2;
+    exit 1;
+}
+
+
+# Try to find a Java runtime and set JAVA_HOME and JAVA_CMD accordingly.
+# If JAVA_CMD exists, nothing is done. If JAVA_HOME exists, only that
+# is searched.
+#
+# In the other cases, the runtime is looked for according to one of the
+# following arguments:
+#  * 2 : java runtime 2 
+#  * swing : a JVM that has swing
+#  * fullxml: a JVM that has all XML classes, including
+#    javax.xml.stream.util.StreamReaderDelegate
+#  * sun: sun's JVM, for stuff depending on the infamous com.sun classes
+#  * sun6: sun's JVM version 6
+#
+# If JAVA_DEBUGGER is set, we try to use jdb rather than java, if it is
+# present.
+#
+# This information is currently *far from complete* !!!
+find_java_runtime() {
+    # First, known runtimes:
+    sun_java="/usr/lib/jvm/java-6-sun /usr/lib/jvm/java-1.5.0-sun /usr/lib/j2sdk1.4-sun /usr/lib/j2*1.[456]-sun"
+    gcj2="/usr/lib/jvm/java-*-gcj-4.* "
+    sablevm="/usr/lib/sablevm"
+    kaffe="/usr/lib/kaffe /usr/lib/kaffe/pthreads /usr/lib/kaffe/jthreads"
+    icedtea="/usr/lib/jvm/java-7-icedtea"
+    cacao="/usr/lib/jvm/cacao"
+
+    # IBM, coming from argouml.sh
+    ibm="/usr/lib/j2*1.[456]-ibm"
+
+    # Then, classes of JVM:
+    all_runtimes="$gcj2 $cacao $sablevm $kaffe $icedtea $sun_java $ibm /usr/lib/jvm/*"
+
+    # Java2 runtimes:
+    java2_runtimes="$gcj2 $iced_tea $sun_java $ibm"
+
+    # Full swing runtimes:
+    full_swing_runtimes="$iced_tea $sun_java $ibm"
+
+    # Sun java apparently has some XML functions more than concurrents:
+    xml_extra="/usr/lib/jvm/java-6-sun /usr/lib/jvm/java-1.5.0-sun"
+
+    if [ "$JAVA_CMD" ]; then
+	java_debug "Using already set JAVA_CMD = $JAVA_CMD"
+	return 0;		# Nothing to do
+    fi
+
+    if [ -z "$JAVA_HOME" ]; then
+        # We now try to look for a reasonable JAVA_HOME.
+        # First, narrow the choices, approximately according to what
+        # was asked
+	case $1 in
+	    # A java2 runtime
+	    2) DIRS=$java2_runtimes
+		;;
+	    swing) DIRS="$icedtea $sun_java";
+		;;
+	    sun) DIRS=$sun_java
+		;;
+	    sun6) DIRS=/usr/lib/jvm/java-6-sun
+		;;
+	    fullxml) DIRS=$xml_extra
+		;;
+	    *) DIRS=$all_runtimes
+		;;
+	esac
+        # And pick up the first one that works
+	for dir in $DIRS; do
+	    if [ -x $dir/bin/java ]; then
+		JAVA_HOME=$dir
+		break;
+	    fi
+	done
+    fi
+    if [ "$JAVA_HOME" ] ; then
+	if [ "$JAVA_DEBUGGER" ] && [ -x "$JAVA_HOME/bin/jdb" ]; then
+	    JAVA_CMD="$JAVA_HOME/bin/jdb"
+	else
+	    JAVA_CMD="$JAVA_HOME/bin/java"
+	fi
+	java_debug "Found JAVA_HOME = $JAVA_HOME"
+	java_debug "Found JAVA_CMD = $JAVA_CMD"
+	return 0		# Fine
+    else
+	java_warning "No java runtime was found for flavor '${1:-none}'"
+	return 1;
+    fi
+}
+
+# Same as find_java_runtime, but fails with an error if
+# nothing is found.
+require_java_runtime() {
+    find_java_runtime "$@" || \
+	java_fail "Unable to find an appropriate java runtime. See java_wrappers(7) for help"
+}
+
+# Find jars and add them to the classpath
+find_jars() {
+    looked_for_jars=1
+    for jar in $@ ; do
+	if [ -r $DESTDIR/usr/share/java/$jar ]; then
+	    JAVA_CLASSPATH=$JAVA_CLASSPATH:$DESTDIR/usr/share/java/$jar
+	elif [ -r $DESTDIR/usr/share/java/$jar.jar ]; then 
+	    JAVA_CLASSPATH=$JAVA_CLASSPATH:$DESTDIR/usr/share/java/$jar.jar
+	else
+	    java_warning "Unable to locate $jar in $DESTDIR/usr/share/java/"
+	fi
+    done
+}
+
+# Adds the first jar found to the classpath. Useful for alternative
+# dependencies.
+find_one_jar_in() {
+    looked_for_jars=1
+    for jar in $@ ; do
+	if [ -r $DESTDIR/usr/share/java/$jar ]; then
+	    JAVA_CLASSPATH=$JAVA_CLASSPATH:$DESTDIR/usr/share/java/$jar
+	    return 0
+	elif [ -r $DESTDIR/usr/share/java/$jar.jar ]; then 
+	    JAVA_CLASSPATH=$JAVA_CLASSPATH:$DESTDIR/usr/share/java/$jar.jar
+	    return 0
+	fi
+    done
+    java_warning "Could fine none of $@ in $DESTDIR/usr/share/java/"
+    return 1
+}
+
+# Runs the program !
+run_java() {
+    if [ -z "$JAVA_CMD" ]; then
+	java_warning "No JAVA_CMD set for run_java, using JAVA_CMD = java"
+	JAVA_CMD=java
+    fi
+    if [ "$FORCE_CLASSPATH" ]; then
+	java_debug "Using unmodified classpath : $FORCE_CLASSPATH";
+	cp="-classpath $FORCE_CLASSPATH";
+    elif [ "$JAVA_CLASSPATH" ]; then
+	cp="-classpath $JAVA_CLASSPATH";
+    else
+	cp="";
+    fi
+    java_debug "Runnning $JAVA_CMD $JAVA_ARGS $cp $@"
+    exec $JAVA_CMD $JAVA_ARGS $cp "$@"
+}
+
+# Runs a java jar.
+# You don't have to use this function.
+run_jar() {
+    if [ "$looked_for_jars" ]; 
+	java_warning "It is most likely useless to use find_jar when running"
+	java_warning "a class with run_jar (-classpath is ignored)"
+    fi
+    run_java -jar "$@"
+}
\ No newline at end of file