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