Merge tag 'mailbox-v5.2' of git://git.linaro.org/landing-teams/working/fujitsu/integr...
[sfrench/cifs-2.6.git] / Documentation / admin-guide / java.rst
1 Java(tm) Binary Kernel Support for Linux v1.03
2 ----------------------------------------------
3
4 Linux beats them ALL! While all other OS's are TALKING about direct
5 support of Java Binaries in the OS, Linux is doing it!
6
7 You can execute Java applications and Java Applets just like any
8 other program after you have done the following:
9
10 1) You MUST FIRST install the Java Developers Kit for Linux.
11    The Java on Linux HOWTO gives the details on getting and
12    installing this. This HOWTO can be found at:
13
14         ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO
15
16    You should also set up a reasonable CLASSPATH environment
17    variable to use Java applications that make use of any
18    nonstandard classes (not included in the same directory
19    as the application itself).
20
21 2) You have to compile BINFMT_MISC either as a module or into
22    the kernel (``CONFIG_BINFMT_MISC``) and set it up properly.
23    If you choose to compile it as a module, you will have
24    to insert it manually with modprobe/insmod, as kmod
25    cannot easily be supported with binfmt_misc.
26    Read the file 'binfmt_misc.txt' in this directory to know
27    more about the configuration process.
28
29 3) Add the following configuration items to binfmt_misc
30    (you should really have read ``binfmt_misc.txt`` now):
31    support for Java applications::
32
33      ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:'
34
35    support for executable Jar files::
36
37      ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:'
38
39    support for Java Applets::
40
41      ':Applet:E::html::/usr/bin/appletviewer:'
42
43    or the following, if you want to be more selective::
44
45      ':Applet:M::<!--applet::/usr/bin/appletviewer:'
46
47    Of course you have to fix the path names. The path/file names given in this
48    document match the Debian 2.1 system. (i.e. jdk installed in ``/usr``,
49    custom wrappers from this document in ``/usr/local``)
50
51    Note, that for the more selective applet support you have to modify
52    existing html-files to contain ``<!--applet-->`` in the first line
53    (``<`` has to be the first character!) to let this work!
54
55    For the compiled Java programs you need a wrapper script like the
56    following (this is because Java is broken in case of the filename
57    handling), again fix the path names, both in the script and in the
58    above given configuration string.
59
60    You, too, need the little program after the script. Compile like::
61
62         gcc -O2 -o javaclassname javaclassname.c
63
64    and stick it to ``/usr/local/bin``.
65
66    Both the javawrapper shellscript and the javaclassname program
67    were supplied by Colin J. Watson <cjw44@cam.ac.uk>.
68
69 Javawrapper shell script:
70
71 .. code-block:: sh
72
73   #!/bin/bash
74   # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java
75
76   if [ -z "$1" ]; then
77         exec 1>&2
78         echo Usage: $0 class-file
79         exit 1
80   fi
81
82   CLASS=$1
83   FQCLASS=`/usr/local/bin/javaclassname $1`
84   FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'`
85   FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'`
86
87   # for example:
88   # CLASS=Test.class
89   # FQCLASS=foo.bar.Test
90   # FQCLASSN=Test
91   # FQCLASSP=foo/bar
92
93   unset CLASSBASE
94
95   declare -i LINKLEVEL=0
96
97   while :; do
98         if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then
99                 # See if this directory works straight off
100                 cd -L `dirname $CLASS`
101                 CLASSDIR=$PWD
102                 cd $OLDPWD
103                 if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
104                         CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
105                         break;
106                 fi
107                 # Try dereferencing the directory name
108                 cd -P `dirname $CLASS`
109                 CLASSDIR=$PWD
110                 cd $OLDPWD
111                 if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
112                         CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
113                         break;
114                 fi
115                 # If no other possible filename exists
116                 if [ ! -L $CLASS ]; then
117                         exec 1>&2
118                         echo $0:
119                         echo "  $CLASS should be in a" \
120                              "directory tree called $FQCLASSP"
121                         exit 1
122                 fi
123         fi
124         if [ ! -L $CLASS ]; then break; fi
125         # Go down one more level of symbolic links
126         let LINKLEVEL+=1
127         if [ $LINKLEVEL -gt 5 ]; then
128                 exec 1>&2
129                 echo $0:
130                 echo "  Too many symbolic links encountered"
131                 exit 1
132         fi
133         CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'`
134   done
135
136   if [ -z "$CLASSBASE" ]; then
137         if [ -z "$FQCLASSP" ]; then
138                 GOODNAME=$FQCLASSN.class
139         else
140                 GOODNAME=$FQCLASSP/$FQCLASSN.class
141         fi
142         exec 1>&2
143         echo $0:
144         echo "  $FQCLASS should be in a file called $GOODNAME"
145         exit 1
146   fi
147
148   if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then
149         # class is not in CLASSPATH, so prepend dir of class to CLASSPATH
150         if [ -z "${CLASSPATH}" ] ; then
151                 export CLASSPATH=$CLASSBASE
152         else
153                 export CLASSPATH=$CLASSBASE:$CLASSPATH
154         fi
155   fi
156
157   shift
158   /usr/bin/java $FQCLASS "$@"
159
160 javaclassname.c:
161
162 .. code-block:: c
163
164   /* javaclassname.c
165    *
166    * Extracts the class name from a Java class file; intended for use in a Java
167    * wrapper of the type supported by the binfmt_misc option in the Linux kernel.
168    *
169    * Copyright (C) 1999 Colin J. Watson <cjw44@cam.ac.uk>.
170    *
171    * This program is free software; you can redistribute it and/or modify
172    * it under the terms of the GNU General Public License as published by
173    * the Free Software Foundation; either version 2 of the License, or
174    * (at your option) any later version.
175    *
176    * This program is distributed in the hope that it will be useful,
177    * but WITHOUT ANY WARRANTY; without even the implied warranty of
178    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
179    * GNU General Public License for more details.
180    *
181    * You should have received a copy of the GNU General Public License
182    * along with this program; if not, write to the Free Software
183    * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
184    */
185
186   #include <stdlib.h>
187   #include <stdio.h>
188   #include <stdarg.h>
189   #include <sys/types.h>
190
191   /* From Sun's Java VM Specification, as tag entries in the constant pool. */
192
193   #define CP_UTF8 1
194   #define CP_INTEGER 3
195   #define CP_FLOAT 4
196   #define CP_LONG 5
197   #define CP_DOUBLE 6
198   #define CP_CLASS 7
199   #define CP_STRING 8
200   #define CP_FIELDREF 9
201   #define CP_METHODREF 10
202   #define CP_INTERFACEMETHODREF 11
203   #define CP_NAMEANDTYPE 12
204   #define CP_METHODHANDLE 15
205   #define CP_METHODTYPE 16
206   #define CP_INVOKEDYNAMIC 18
207
208   /* Define some commonly used error messages */
209
210   #define seek_error() error("%s: Cannot seek\n", program)
211   #define corrupt_error() error("%s: Class file corrupt\n", program)
212   #define eof_error() error("%s: Unexpected end of file\n", program)
213   #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program);
214
215   char *program;
216
217   long *pool;
218
219   u_int8_t read_8(FILE *classfile);
220   u_int16_t read_16(FILE *classfile);
221   void skip_constant(FILE *classfile, u_int16_t *cur);
222   void error(const char *format, ...);
223   int main(int argc, char **argv);
224
225   /* Reads in an unsigned 8-bit integer. */
226   u_int8_t read_8(FILE *classfile)
227   {
228         int b = fgetc(classfile);
229         if(b == EOF)
230                 eof_error();
231         return (u_int8_t)b;
232   }
233
234   /* Reads in an unsigned 16-bit integer. */
235   u_int16_t read_16(FILE *classfile)
236   {
237         int b1, b2;
238         b1 = fgetc(classfile);
239         if(b1 == EOF)
240                 eof_error();
241         b2 = fgetc(classfile);
242         if(b2 == EOF)
243                 eof_error();
244         return (u_int16_t)((b1 << 8) | b2);
245   }
246
247   /* Reads in a value from the constant pool. */
248   void skip_constant(FILE *classfile, u_int16_t *cur)
249   {
250         u_int16_t len;
251         int seekerr = 1;
252         pool[*cur] = ftell(classfile);
253         switch(read_8(classfile))
254         {
255         case CP_UTF8:
256                 len = read_16(classfile);
257                 seekerr = fseek(classfile, len, SEEK_CUR);
258                 break;
259         case CP_CLASS:
260         case CP_STRING:
261         case CP_METHODTYPE:
262                 seekerr = fseek(classfile, 2, SEEK_CUR);
263                 break;
264         case CP_METHODHANDLE:
265                 seekerr = fseek(classfile, 3, SEEK_CUR);
266                 break;
267         case CP_INTEGER:
268         case CP_FLOAT:
269         case CP_FIELDREF:
270         case CP_METHODREF:
271         case CP_INTERFACEMETHODREF:
272         case CP_NAMEANDTYPE:
273         case CP_INVOKEDYNAMIC:
274                 seekerr = fseek(classfile, 4, SEEK_CUR);
275                 break;
276         case CP_LONG:
277         case CP_DOUBLE:
278                 seekerr = fseek(classfile, 8, SEEK_CUR);
279                 ++(*cur);
280                 break;
281         default:
282                 corrupt_error();
283         }
284         if(seekerr)
285                 seek_error();
286   }
287
288   void error(const char *format, ...)
289   {
290         va_list ap;
291         va_start(ap, format);
292         vfprintf(stderr, format, ap);
293         va_end(ap);
294         exit(1);
295   }
296
297   int main(int argc, char **argv)
298   {
299         FILE *classfile;
300         u_int16_t cp_count, i, this_class, classinfo_ptr;
301         u_int8_t length;
302
303         program = argv[0];
304
305         if(!argv[1])
306                 error("%s: Missing input file\n", program);
307         classfile = fopen(argv[1], "rb");
308         if(!classfile)
309                 error("%s: Error opening %s\n", program, argv[1]);
310
311         if(fseek(classfile, 8, SEEK_SET))  /* skip magic and version numbers */
312                 seek_error();
313         cp_count = read_16(classfile);
314         pool = calloc(cp_count, sizeof(long));
315         if(!pool)
316                 error("%s: Out of memory for constant pool\n", program);
317
318         for(i = 1; i < cp_count; ++i)
319                 skip_constant(classfile, &i);
320         if(fseek(classfile, 2, SEEK_CUR))       /* skip access flags */
321                 seek_error();
322
323         this_class = read_16(classfile);
324         if(this_class < 1 || this_class >= cp_count)
325                 corrupt_error();
326         if(!pool[this_class] || pool[this_class] == -1)
327                 corrupt_error();
328         if(fseek(classfile, pool[this_class] + 1, SEEK_SET))
329                 seek_error();
330
331         classinfo_ptr = read_16(classfile);
332         if(classinfo_ptr < 1 || classinfo_ptr >= cp_count)
333                 corrupt_error();
334         if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1)
335                 corrupt_error();
336         if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET))
337                 seek_error();
338
339         length = read_16(classfile);
340         for(i = 0; i < length; ++i)
341         {
342                 u_int8_t x = read_8(classfile);
343                 if((x & 0x80) || !x)
344                 {
345                         if((x & 0xE0) == 0xC0)
346                         {
347                                 u_int8_t y = read_8(classfile);
348                                 if((y & 0xC0) == 0x80)
349                                 {
350                                         int c = ((x & 0x1f) << 6) + (y & 0x3f);
351                                         if(c) putchar(c);
352                                         else utf8_error();
353                                 }
354                                 else utf8_error();
355                         }
356                         else utf8_error();
357                 }
358                 else if(x == '/') putchar('.');
359                 else putchar(x);
360         }
361         putchar('\n');
362         free(pool);
363         fclose(classfile);
364         return 0;
365   }
366
367 jarwrapper::
368
369   #!/bin/bash
370   # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar
371
372   java -jar $1
373
374
375 Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you
376 want to execute.
377
378 To add a Java program to your path best put a symbolic link to the main
379 .class file into /usr/bin (or another place you like) omitting the .class
380 extension. The directory containing the original .class file will be
381 added to your CLASSPATH during execution.
382
383
384 To test your new setup, enter in the following simple Java app, and name
385 it "HelloWorld.java":
386
387 .. code-block:: java
388
389         class HelloWorld {
390                 public static void main(String args[]) {
391                         System.out.println("Hello World!");
392                 }
393         }
394
395 Now compile the application with::
396
397         javac HelloWorld.java
398
399 Set the executable permissions of the binary file, with::
400
401         chmod 755 HelloWorld.class
402
403 And then execute it::
404
405         ./HelloWorld.class
406
407
408 To execute Java Jar files, simple chmod the ``*.jar`` files to include
409 the execution bit, then just do::
410
411        ./Application.jar
412
413
414 To execute Java Applets, simple chmod the ``*.html`` files to include
415 the execution bit, then just do::
416
417         ./Applet.html
418
419
420 originally by Brian A. Lantz, brian@lantz.com
421 heavily edited for binfmt_misc by Richard G√ľnther
422 new scripts by Colin J. Watson <cjw44@cam.ac.uk>
423 added executable Jar file support by Kurt Huwig <kurt@iku-netz.de>