ae33d959638c79921e5712bdba36ef26f813434a
[sfrench/cifs-2.6.git] / Documentation / java.txt
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   #!/bin/bash
72   # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java
73
74   if [ -z "$1" ]; then
75         exec 1>&2
76         echo Usage: $0 class-file
77         exit 1
78   fi
79
80   CLASS=$1
81   FQCLASS=`/usr/local/bin/javaclassname $1`
82   FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'`
83   FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'`
84
85   # for example:
86   # CLASS=Test.class
87   # FQCLASS=foo.bar.Test
88   # FQCLASSN=Test
89   # FQCLASSP=foo/bar
90
91   unset CLASSBASE
92
93   declare -i LINKLEVEL=0
94
95   while :; do
96         if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then
97                 # See if this directory works straight off
98                 cd -L `dirname $CLASS`
99                 CLASSDIR=$PWD
100                 cd $OLDPWD
101                 if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
102                         CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
103                         break;
104                 fi
105                 # Try dereferencing the directory name
106                 cd -P `dirname $CLASS`
107                 CLASSDIR=$PWD
108                 cd $OLDPWD
109                 if echo $CLASSDIR | grep -q "$FQCLASSP$"; then
110                         CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."`
111                         break;
112                 fi
113                 # If no other possible filename exists
114                 if [ ! -L $CLASS ]; then
115                         exec 1>&2
116                         echo $0:
117                         echo "  $CLASS should be in a" \
118                              "directory tree called $FQCLASSP"
119                         exit 1
120                 fi
121         fi
122         if [ ! -L $CLASS ]; then break; fi
123         # Go down one more level of symbolic links
124         let LINKLEVEL+=1
125         if [ $LINKLEVEL -gt 5 ]; then
126                 exec 1>&2
127                 echo $0:
128                 echo "  Too many symbolic links encountered"
129                 exit 1
130         fi
131         CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'`
132   done
133
134   if [ -z "$CLASSBASE" ]; then
135         if [ -z "$FQCLASSP" ]; then
136                 GOODNAME=$FQCLASSN.class
137         else
138                 GOODNAME=$FQCLASSP/$FQCLASSN.class
139         fi
140         exec 1>&2
141         echo $0:
142         echo "  $FQCLASS should be in a file called $GOODNAME"
143         exit 1
144   fi
145
146   if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then
147         # class is not in CLASSPATH, so prepend dir of class to CLASSPATH
148         if [ -z "${CLASSPATH}" ] ; then
149                 export CLASSPATH=$CLASSBASE
150         else
151                 export CLASSPATH=$CLASSBASE:$CLASSPATH
152         fi
153   fi
154
155   shift
156   /usr/bin/java $FQCLASS "$@"
157
158 javaclassname.c::
159
160   /* javaclassname.c
161  *
162  * Extracts the class name from a Java class file; intended for use in a Java
163  * wrapper of the type supported by the binfmt_misc option in the Linux kernel.
164  *
165  * Copyright (C) 1999 Colin J. Watson <cjw44@cam.ac.uk>.
166  *
167  * This program is free software; you can redistribute it and/or modify
168  * it under the terms of the GNU General Public License as published by
169  * the Free Software Foundation; either version 2 of the License, or
170  * (at your option) any later version.
171  *
172  * This program is distributed in the hope that it will be useful,
173  * but WITHOUT ANY WARRANTY; without even the implied warranty of
174  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
175  * GNU General Public License for more details.
176  *
177  * You should have received a copy of the GNU General Public License
178  * along with this program; if not, write to the Free Software
179  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
180  */
181
182   #include <stdlib.h>
183   #include <stdio.h>
184   #include <stdarg.h>
185   #include <sys/types.h>
186
187   /* From Sun's Java VM Specification, as tag entries in the constant pool. */
188
189   #define CP_UTF8 1
190   #define CP_INTEGER 3
191   #define CP_FLOAT 4
192   #define CP_LONG 5
193   #define CP_DOUBLE 6
194   #define CP_CLASS 7
195   #define CP_STRING 8
196   #define CP_FIELDREF 9
197   #define CP_METHODREF 10
198   #define CP_INTERFACEMETHODREF 11
199   #define CP_NAMEANDTYPE 12
200   #define CP_METHODHANDLE 15
201   #define CP_METHODTYPE 16
202   #define CP_INVOKEDYNAMIC 18
203
204   /* Define some commonly used error messages */
205
206   #define seek_error() error("%s: Cannot seek\n", program)
207   #define corrupt_error() error("%s: Class file corrupt\n", program)
208   #define eof_error() error("%s: Unexpected end of file\n", program)
209   #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program);
210
211   char *program;
212
213   long *pool;
214
215   u_int8_t read_8(FILE *classfile);
216   u_int16_t read_16(FILE *classfile);
217   void skip_constant(FILE *classfile, u_int16_t *cur);
218   void error(const char *format, ...);
219   int main(int argc, char **argv);
220
221   /* Reads in an unsigned 8-bit integer. */
222   u_int8_t read_8(FILE *classfile)
223   {
224         int b = fgetc(classfile);
225         if(b == EOF)
226                 eof_error();
227         return (u_int8_t)b;
228   }
229
230   /* Reads in an unsigned 16-bit integer. */
231   u_int16_t read_16(FILE *classfile)
232   {
233         int b1, b2;
234         b1 = fgetc(classfile);
235         if(b1 == EOF)
236                 eof_error();
237         b2 = fgetc(classfile);
238         if(b2 == EOF)
239                 eof_error();
240         return (u_int16_t)((b1 << 8) | b2);
241   }
242
243   /* Reads in a value from the constant pool. */
244   void skip_constant(FILE *classfile, u_int16_t *cur)
245   {
246         u_int16_t len;
247         int seekerr = 1;
248         pool[*cur] = ftell(classfile);
249         switch(read_8(classfile))
250         {
251         case CP_UTF8:
252                 len = read_16(classfile);
253                 seekerr = fseek(classfile, len, SEEK_CUR);
254                 break;
255         case CP_CLASS:
256         case CP_STRING:
257         case CP_METHODTYPE:
258                 seekerr = fseek(classfile, 2, SEEK_CUR);
259                 break;
260         case CP_METHODHANDLE:
261                 seekerr = fseek(classfile, 3, SEEK_CUR);
262                 break;
263         case CP_INTEGER:
264         case CP_FLOAT:
265         case CP_FIELDREF:
266         case CP_METHODREF:
267         case CP_INTERFACEMETHODREF:
268         case CP_NAMEANDTYPE:
269         case CP_INVOKEDYNAMIC:
270                 seekerr = fseek(classfile, 4, SEEK_CUR);
271                 break;
272         case CP_LONG:
273         case CP_DOUBLE:
274                 seekerr = fseek(classfile, 8, SEEK_CUR);
275                 ++(*cur);
276                 break;
277         default:
278                 corrupt_error();
279         }
280         if(seekerr)
281                 seek_error();
282   }
283
284   void error(const char *format, ...)
285   {
286         va_list ap;
287         va_start(ap, format);
288         vfprintf(stderr, format, ap);
289         va_end(ap);
290         exit(1);
291   }
292
293   int main(int argc, char **argv)
294   {
295         FILE *classfile;
296         u_int16_t cp_count, i, this_class, classinfo_ptr;
297         u_int8_t length;
298
299         program = argv[0];
300
301         if(!argv[1])
302                 error("%s: Missing input file\n", program);
303         classfile = fopen(argv[1], "rb");
304         if(!classfile)
305                 error("%s: Error opening %s\n", program, argv[1]);
306
307         if(fseek(classfile, 8, SEEK_SET))  /* skip magic and version numbers */
308                 seek_error();
309         cp_count = read_16(classfile);
310         pool = calloc(cp_count, sizeof(long));
311         if(!pool)
312                 error("%s: Out of memory for constant pool\n", program);
313
314         for(i = 1; i < cp_count; ++i)
315                 skip_constant(classfile, &i);
316         if(fseek(classfile, 2, SEEK_CUR))       /* skip access flags */
317                 seek_error();
318
319         this_class = read_16(classfile);
320         if(this_class < 1 || this_class >= cp_count)
321                 corrupt_error();
322         if(!pool[this_class] || pool[this_class] == -1)
323                 corrupt_error();
324         if(fseek(classfile, pool[this_class] + 1, SEEK_SET))
325                 seek_error();
326
327         classinfo_ptr = read_16(classfile);
328         if(classinfo_ptr < 1 || classinfo_ptr >= cp_count)
329                 corrupt_error();
330         if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1)
331                 corrupt_error();
332         if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET))
333                 seek_error();
334
335         length = read_16(classfile);
336         for(i = 0; i < length; ++i)
337         {
338                 u_int8_t x = read_8(classfile);
339                 if((x & 0x80) || !x)
340                 {
341                         if((x & 0xE0) == 0xC0)
342                         {
343                                 u_int8_t y = read_8(classfile);
344                                 if((y & 0xC0) == 0x80)
345                                 {
346                                         int c = ((x & 0x1f) << 6) + (y & 0x3f);
347                                         if(c) putchar(c);
348                                         else utf8_error();
349                                 }
350                                 else utf8_error();
351                         }
352                         else utf8_error();
353                 }
354                 else if(x == '/') putchar('.');
355                 else putchar(x);
356         }
357         putchar('\n');
358         free(pool);
359         fclose(classfile);
360         return 0;
361   }
362
363 jarwrapper::
364
365   #!/bin/bash
366   # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar
367
368   java -jar $1
369
370
371 Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you
372 want to execute.
373
374 To add a Java program to your path best put a symbolic link to the main
375 .class file into /usr/bin (or another place you like) omitting the .class
376 extension. The directory containing the original .class file will be
377 added to your CLASSPATH during execution.
378
379
380 To test your new setup, enter in the following simple Java app, and name
381 it "HelloWorld.java"::
382
383         class HelloWorld {
384                 public static void main(String args[]) {
385                         System.out.println("Hello World!");
386                 }
387         }
388
389 Now compile the application with::
390
391         javac HelloWorld.java
392
393 Set the executable permissions of the binary file, with::
394
395         chmod 755 HelloWorld.class
396
397 And then execute it::
398
399         ./HelloWorld.class
400
401
402 To execute Java Jar files, simple chmod the ``*.jar`` files to include
403 the execution bit, then just do::
404
405        ./Application.jar
406
407
408 To execute Java Applets, simple chmod the ``*.html`` files to include
409 the execution bit, then just do::
410
411         ./Applet.html
412
413
414 originally by Brian A. Lantz, brian@lantz.com
415 heavily edited for binfmt_misc by Richard G√ľnther
416 new scripts by Colin J. Watson <cjw44@cam.ac.uk>
417 added executable Jar file support by Kurt Huwig <kurt@iku-netz.de>
418