java-wrappers/0.1.25/java-wrappers.7

\" 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 "2010-05-04" "Version 0.1.16" "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_BINDIR
Specifies a directory that will be looked for a 
.I java
or a 
.I jdb
executable (depending on the setting of
.IR JAVA_DEBUGGER ).
It has precedence over 
.I JAVA_HOME
but not over
.IR JAVA_CMD .


.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_FLAVOR
A probably more easy-to-use version of the 
.I 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
.IR /usr/lib/java-wrappers/jvm-list.sh .
See examples below.


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

.TP
.B JAVA_JARPATH
The path where the wrappers will go looking for 
.I jar
archives. If not set, the wrapper will look into the default
directory,
.IR /usr/share/java .
.B Warning :
the wrapper will not look anywhere else than in 
.IR JAVA_JARPATH .
Setting it incorrectly will most probably result in early crashes.

.SH EXAMPLES

The examples all rely on 
.BR rasterizer (1),
from the package
.B libbatik-java\fR,
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

The same, but using 
.IR JAVA_BINDIR :

.I JAVA_BINDIR=/usr/lib/kaffe/bin rasterizer

Force rasterizer to run with 
.BR openjdk :

.I JAVA_FLAVOR=openjdk 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 BUGS

Care has been taken to make the wrappers bug-free. If that was not
the case, please file a bug report against the
.B java-wrappers
package.

If you wish to submit any problem with a java executable relying on
.BR java-wrappers ,
please also submit the output of the command run with
.IR DEBUG_WRAPPER=1 .
It will save one mail exchange and therefore potentially reduce the
time it takes to fix the bug.

.SH DEVELOPERS

There is currently no documentation about writing a wrapper script
save the comments in
.IR /usr/lib/java-wrappers/java-wrappers.sh .
If you have to write one, we suggest you base yourself upon, for
instance, the 
.I rasterizer
wrapper script, or any other one (just pick up any direct reverse
dependency of 
.B java-wrappers
and look for scripts).

.SH SEE ALSO

.BR java (1),
.BR jdb (1)

.I /usr/lib/java-wrappers/java-wrappers.sh

.SH AUTHOR

.B java-wrappers
and its documentation were written by 
Vincent Fourmond <fourmond@debian.org>
1	\" Man page documenting the java-wrappers
2	\"
3	\" Copyright 2008 by Vincent Fourmond
4	\"
5	\" This documentation is free software; you can redistribute it and/or modify
6	\" it under the terms of the GNU General Public License as published by
7	\" the Free Software Foundation; either version 2 of the License, or
8	\" (at your option) any later version.
9
10	\" This package is distributed in the hope that it will be useful,
11	\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12	\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13	\" GNU General Public License for more details.
14
15	\" You should have received a copy of the GNU General Public License
16	\" along with this program; if not, write to the Free Software
17	\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18	.TH JAVA-WRAPPERS 7 "2010-05-04" "Version 0.1.16" "Java wrappers"
19
20	.SH NAME
21	.B java-wrappers
22	\- capacities shared by java wrapper scripts
23
24	.SH DESCRIPTION
25
26	Most Java programs are not run directly, but through small shell
27	scripts that take care of various things, such as finding a suitable
28	java environment and looking for libraries.
29
30	To ease the task of the maintainers, they rely on a library providing
31	runtime detection, library detection and other features. This manual
32	page describes the common features of all those scripts, and to which
33	point you can configure them. This is mainly done via environment
34	variables.
35
36	.SH ENVIRONMENT VARIABLES
37
38	.B java-wrappers
39	understands some environment variables:
40
41	.TP
42	.B JAVA_CMD
43	The
44	.I java
45	command that will be run. If this variable is set, it disables all
46	lookup for a java runtime.
47
48	.TP
49	.B JAVA_BINDIR
50	Specifies a directory that will be looked for a
51	.I java
52	or a
53	.I jdb
54	executable (depending on the setting of
55	.IR JAVA_DEBUGGER ).
56	It has precedence over
57	.I JAVA_HOME
58	but not over
59	.IR JAVA_CMD .
60
61
62	.TP
63	.B JAVA_HOME
64	A path to a java runtime. If this variable is set, all lookup for a
65	java runtime is disabled, except that if no
66	.I java
67	executable is found in the path, the command
68	.I java
69	is used.
70
71	.TP
72	.B JAVA_FLAVOR
73	A probably more easy-to-use version of the
74	.I JAVA_HOME
75	variable: instead of specifying the full path of the java runtime, you
76	name it. List of available flavors can be found in the file
77	.IR /usr/lib/java-wrappers/jvm-list.sh .
78	See examples below.
79
80
81	.TP
82	.B JAVA_DEBUGGER
83	If this is set, the wrapper will try to pick up a java debugger rather
84	than a java interpreter. This will fail if the
85	.I jbd
86	of the runtime found is a stub.
87
88	.TP
89	.B JAVA_CLASSPATH
90	Additional classpath, will have priority over the one found by the
91	wrapper.
92
93	.TP
94	.B JAVA_ARGS
95	Additional arguments to the
96	.I java
97	command. They will come before all other arguments.
98
99	.TP
100	.B FORCE_CLASSPATH
101	If this variable is set, it will be
102	.B the only classpath\fR.
103	You'd better know what you are doing.
104
105	.TP
106	.B DEBUG_WRAPPER
107	This is probably the most important variable; if it set, the wrapper
108	will print out useful information as it goes by its business, such as
109	which runtime it did find, and which command is run eventually.
110
111	.TP
112	.B JAVA_JARPATH
113	The path where the wrappers will go looking for
114	.I jar
115	archives. If not set, the wrapper will look into the default
116	directory,
117	.IR /usr/share/java .
118	.B Warning :
119	the wrapper will not look anywhere else than in
120	.IR JAVA_JARPATH .
121	Setting it incorrectly will most probably result in early crashes.
122
123	.SH EXAMPLES
124
125	The examples all rely on
126	.BR rasterizer (1),
127	from the package
128	.B libbatik-java\fR,
129	but they really apply to all scripts that use java-wrappers.
130
131	Print out debugging information:
132
133	.I DEBUG_WRAPPER=1 rasterizer
134
135	Limit rasterizer's memory to 80 MB:
136
137	.I JAVA_ARGS=-Xmx80m rasterizer
138
139	Force rasterizer to run with
140	.BR kaffe (1):
141
142	.I JAVA_HOME=/usr/lib/kaffe rasterizer
143
144	The same, but using
145	.IR JAVA_BINDIR :
146
147	.I JAVA_BINDIR=/usr/lib/kaffe/bin rasterizer
148
149	Force rasterizer to run with
150	.BR openjdk :
151
152	.I JAVA_FLAVOR=openjdk rasterizer
153
154
155	Debug rasterizer with Sun's debugger, while printing debugging
156	information from the wrapper:
157
158	.I DEBUG_WRAPPER=1 JAVA_CMD=/usr/lib/jvm/java-6-sun/bin/jdb rasterizer
159
160	.SH BUGS
161
162	Care has been taken to make the wrappers bug-free. If that was not
163	the case, please file a bug report against the
164	.B java-wrappers
165	package.
166
167	If you wish to submit any problem with a java executable relying on
168	.BR java-wrappers ,
169	please also submit the output of the command run with
170	.IR DEBUG_WRAPPER=1 .
171	It will save one mail exchange and therefore potentially reduce the
172	time it takes to fix the bug.
173
174	.SH DEVELOPERS
175
176	There is currently no documentation about writing a wrapper script
177	save the comments in
178	.IR /usr/lib/java-wrappers/java-wrappers.sh .
179	If you have to write one, we suggest you base yourself upon, for
180	instance, the
181	.I rasterizer
182	wrapper script, or any other one (just pick up any direct reverse
183	dependency of
184	.B java-wrappers
185	and look for scripts).
186
187	.SH SEE ALSO
188
189	.BR java (1),
190	.BR jdb (1)
191
192	.I /usr/lib/java-wrappers/java-wrappers.sh
193
194	.SH AUTHOR
195
196	.B java-wrappers
197	and its documentation were written by
198	Vincent Fourmond <fourmond@debian.org>