home *** CD-ROM | disk | FTP | other *** search
/ PC Plus SuperCD (UK) 1999 October / pcp156b.iso / alphawrk / LINUXJVM / README.HTML < prev   
Encoding:
Text File  |  1999-07-08  |  16.2 KB  |  421 lines
  1.  
  2. IBM Developer Kit for Linux(R), Java(TM) Technology Edition, alphaVersion 1.1.6
  3. ===============================================================================
  4.  
  5. -----------------------------------------------------------------------
  6. CONTENTS
  7.  
  8.   Overview of the IBM Developer Kit
  9.     - Introduction
  10.     - Just-In-Time(JIT) Compiler
  11.     - What the Software Contains
  12.     - Where to Find More Information
  13.  
  14.   Running the Software
  15.     - Linux(R) System Pre-requisites
  16.     - Running IBM Developer Kit Tools under Linux
  17.     - Linux PATH and CLASSPATH
  18.     - Linux Installation Troubleshooting
  19.     - Running Applets with the AppletViewer
  20.     - Debugging Programs with the Debugger
  21.     - Known Problems with the Alpha version
  22.  
  23. =======================================================================
  24.                  Overview of the IBM Developer Kit
  25. =======================================================================
  26.  
  27. _____________
  28. INTRODUCTION
  29.  
  30. The Software is provided as a gzipped tar package named 
  31. ibm-jdk-l116-linux-x86.tgz.This alpha version of the IBM Developer Kit
  32. is dependent on certain levels of the kernel and C runtime libraries 
  33. in your Linux installation.  Please see the section "Linux System 
  34. Pre-requisites" under "Running the Software" later in this document 
  35. for a full discussion of these dependencies.
  36.  
  37. The IBM build number can be obtained by entering:
  38.   java -fullversion
  39. or
  40.   jre -d
  41.  
  42. This is an alpha version 1.1.6 of the IBM Developer Kit.  The IBM
  43. Developer Kit is a development environment for writing applets
  44. and applications that conform to the Java 1.1 Core API.  Its compiler
  45. and other tools are run from a shell and have no GUI interface. 
  46.  
  47.  
  48. All IBM Developer Kit tools use the IBM JIT (libjitc.so) by default. To
  49. disable the JIT, see "Using the JIT" below.
  50.  
  51.  
  52. ____________________
  53. Just-In-Time Compiler
  54.  
  55. The IBM Developer Kit includes the IBM JIT (libjitc.so) which is used by
  56. all tools by default. To disable the JIT, the following additions to the
  57. command line options can be used:
  58.  
  59.   java -Djava.compiler=off MyClass
  60.   jre -nojit MyClass
  61.  
  62. With the java tool, setting JAVA_COMPILER also affects JIT usage.
  63. JAVA_COMPILER=off may be used to disable the JIT. The JRE tool 
  64. ignores JAVA_COMPILER. Both tools also use the java.compiler 
  65. property to determine JIT usage. See the appropriate tool 
  66. documentation.
  67.  
  68. Whether or not the JIT will be used can be determined by entering:
  69.   jre -d
  70. or
  71.   java -fullversion
  72.  
  73. If the JIT is in use, this will be indicated by
  74.   (JIT enabled: jitc)
  75. at the end of the fullversion string for the java command, or
  76.   compiler = enabled: jitc
  77. for the jre.
  78. If the JIT is not in use, this will be indicated by
  79.   (JIT disabled)
  80. or
  81.   compiler = disabled
  82.  
  83.  
  84. ______________________________
  85. WHAT THE SOFTWARE CONTAINS
  86.  
  87. RUNTIME 
  88.  
  89.     - Core Classes (classes.zip)
  90.             DO NOT UNZIP THIS FILE!  It must remain zipped for the
  91.             compiler and interpreter to access the class files
  92.             within it properly.  This file contains all of the
  93.             compiled .class files for the platform.
  94.  
  95. TOOLS 
  96.  
  97.     - Java Compiler (javac)
  98.             Compiles programs written in the Java programming language
  99.             into bytecodes.
  100.  
  101.     - Java Interpreter (java)
  102.             Executes Java bytecodes.  In other words, it runs
  103.             programs written in the Java programming language.
  104.  
  105.     - Java Runtime Interpreter (jre)
  106.             Similar to the Java Interpreter (java), but intended for
  107.             end users who do not require all the development-related
  108.             options available with the java tool.
  109.  
  110.     - Java AppletViewer (appletviewer)
  111.             Used for testing and running applets.
  112.  
  113.     - Java Debugger (jdb)
  114.             Helps you find bugs in programs.
  115.  
  116.     - Class File Disassembler (javap)
  117.             Disassembles compiled files and prints out a
  118.             representation of the bytecodes.
  119.  
  120.     - Java Documentation Generator (javadoc)
  121.             Parses the declarations and documentation comments in
  122.             a set of source files and produces a set of HTML pages
  123.             describing the public and protected classes, interfaces,
  124.             constructors, methods, and fields. Also produces
  125.             a class hierarchy and an index of all members.
  126.  
  127.     - C Header and Stub File Generator (javah)
  128.             For attaching native methods to code written in the
  129.             Java programming language.
  130.  
  131.     - Java Archive Tool (jar)
  132.             Combines many class files and other resources
  133.             into a single jar file.
  134.  
  135.     - Digital Signing Tool (javakey)
  136.             Manages entities, including their keys, certificates,
  137.             and the trust associated with them.
  138.  
  139.     - Native-To-ASCII Converter (native2ascii)
  140.             Converts a native encoding file to an ascii
  141.             file that includes the \udddd Unicode notation.
  142.  
  143.     - Java RMI Stub Converter (rmic)
  144.             Generates objects from the names of compiled classes
  145.             that contain remote object implementations.
  146.  
  147.     - Java Remote Object Registry (rmiregistry)
  148.             Creates and starts a remote object registry on the
  149.             specified port of the current host.
  150.  
  151.     - Serial Version Command (serialver)
  152.             Returns the serialVersionUID for one or more classes
  153.             in a form suitable for copying into an evolving class.
  154.  
  155.     - Various C libraries and include files
  156.  
  157. JAVA DOCUMENTATION 
  158.  
  159.     - README
  160.             The file you are currently reading
  161.  
  162.     - LICENSE
  163.             License agreement & Copyright notice for the software
  164.  
  165. ________________________________
  166. WHERE TO FIND MORE INFORMATION
  167.  
  168. You may find additional Java Development Kit, Version 1.1 
  169. documentation by visiting the Sun web site at:
  170.         http://java.sun.com/products/jdk/1.1/
  171.  
  172.  
  173.  
  174. =======================================================================
  175.                        RUNNING THE SOFTWARE
  176. =======================================================================
  177.  
  178. __________________________
  179. Linux System Pre-requisites
  180.  
  181. Because the IBM Developer Kit (Software) uses native threads as the underlying 
  182. implementation of the java.lang.Thread class in the Java core classes,
  183. there are two major pre-requisites for this Software to run correctly on
  184. Linux.  Both are related to the pthreads implementation available on
  185. Linux.  LinuxThreads is the Linux POSIX threads implementation package 
  186. which is built into glibc2, the GNU C runtime library version 2. In
  187. version 2.0 of glibc, LinuxThreads did not have all the functionality
  188. required by the Software.  Version 2.1 of glibc has this required 
  189. functionality, but some of this functionality is also dependant on the
  190. 2.2 version of the Linux kernel.  Therefore, the Software requires
  191. that your Linux installation has both a version of the 2.2 Linux kernel and
  192. a version of glibc that is version 2.1 or greater.  Of the four Linux 
  193. distributions tested, we have made the following notes on each:
  194.  
  195.  * RedHat(R) Linux 6.0(TM)
  196.     - incorporates both glibc version 2.1 and Linux kernel version 2.2.5
  197.  * Caldera Systems, Inc(R) OpenLinux(TM) 2.2
  198.     - incorporates both glibc version 2.1 and Linux kernel version 2.2.x
  199.  * Pacific HiTech TurboLinux 3.6(TM)
  200.     - incorporates Linux kernel version 2.2.9 but only glibc version 2.0.7
  201.  * S.u.S.E Linux 6.1(TM)
  202.     - incorporates Linux kernel version 2.2.5 but only glibc version 2.0.7
  203.     
  204. For users who have Pacific HiTech TurboLinux 3.6 and SuSE Linux 6.1, 
  205. you must upgrade the glibc version on your system so that you are able 
  206. to use the IBM Developer Kit with your system. Please see 
  207. ftp://glibc.cygnus.com/pub/glibc for source and documentation on 
  208. building glibc 2.1 for your system.
  209.  
  210. If you have a version of the Linux Operating System that does not have
  211. version 2.2 or above, of the Linux kernel, please see 
  212. http://www.kernel.org for information on upgrading your system with a 
  213. 2.2.x version of the Linux kernel.
  214.  
  215. _________________________________________
  216. Running IBM Developer Kit Tools under Linux
  217.  
  218. After installing the Software, you start a tool by typing its
  219. name into a terminal window with a filename as an argument.  None of
  220. the main tools have GUI interfaces -- they are all run from the 
  221. terminal command line.
  222.  
  223. You can specify the path to a tool either by typing the path in
  224. front of the tool each time, or by adding the path to your shell's
  225. startup file.  For example, if the Software is installed at
  226. /usr/java, to run the compiler on a file myfile.java, go to a shell
  227. prompt and execute this:
  228.  
  229.     Type:  /usr/java/bin/javac myfile.java
  230.  
  231.      -or-
  232.  
  233.     Add    /usr/java/bin to your PATH statement
  234.     Type:  javac myfile.java
  235.  
  236. See the next section about setting the PATH and CLASSPATH variables.
  237.  
  238. __________________________
  239. Linux PATH and CLASSPATH
  240.  
  241. The CLASSPATH is not required, but if it is set, it will need to be
  242. unset.  You may want to update the "PATH" variable for convenience.
  243.  
  244.      Developing with multiple Java Virtual Machines - If you want
  245.      to develop with the IBM Developer Kit and another Java Virtual
  246.      Machine, you must set CLASSPATH (and PATH) separately
  247.      for each one. To run both versions simultaneously,
  248.      you can run each one from its own shell.  If you are running
  249.      only one at a time, you can write a shell script to
  250.      switch the value of CLASSPATH (and PATH).
  251.  
  252.   1. PATH -  Add the absolute path of the "java/bin"
  253.      directory to your PATH statement as follows.
  254.  
  255.      The PATH statement enables Linux to find the executables
  256.      (javac, java, javadoc, etc.) from any current directory.
  257.  
  258.      To find out the current value of your PATH, at the
  259.      shell prompt type:
  260.  
  261.          $ echo $PATH
  262.  
  263.      To change the PATH, open your shell startup file (usually
  264.      .profile, .bash_profile, .login depending on your shell)
  265.      and make the change to the PATH statement.
  266.  
  267.      To make the path take effect, re-login or re-execute your
  268.      shell startup code.
  269.  
  270.   2. CLASSPATH Environment Variable - If you follow the default
  271.      installation, you do not need to set CLASSPATH, because the
  272.      tools automatically set it for you.
  273.  
  274.      WHAT CLASSPATH DOES
  275.  
  276.        The CLASSPATH tells the Java virtual machine and the
  277.        applications (which are located in the "java/bin"
  278.        directory) where to find the class libraries, such as
  279.        classes.zip file (which is in the lib directory).
  280.        By default, the java tools temporarily append the
  281.        following to whatever CLASSPATH you have explicitly
  282.        set in your startup file:
  283.  
  284.        [bin]/../lib/classes.zip
  285.  
  286.        where [bin] is substituted by the absolute path to the
  287.        java/bin directory.  Therefore, if you keep the bin and
  288.        lib directories at the same directory level (that is, if
  289.        they have a common parent directory), the executables
  290.        will find the classes.  You need to set the CLASSPATH only
  291.        if you move classes.zip or want to load a different library
  292.        (such as one you develop).
  293.  
  294.      Refer to the Linux Installation Troubleshooting section below
  295.      if you have problems running the software.
  296.  
  297.  
  298. _______________________________
  299. Linux Installation Troubleshooting
  300.  
  301. Here are some troubleshooting tips for Linux.
  302.  
  303.    * If, when you try to start any of the tools, you get an
  304.      error from Linux stating that the libjava.so library could
  305.      not be loaded because of a symbol not found (such as __bzero),
  306.      this is reporting that the C runtime library is not at the
  307.      correct level necessary to run the IBM Developer Kit tools.
  308.      The IBM Developer Kit relies upon the native threads
  309.      implementation (pthreads) that is built into glibc version
  310.      2.1.  If your version of Linux was not shipped with glibc
  311.      version 2.1 you will need to upgrade your C runtime library
  312.      to version 2.1.  See the "Linux System Pre-requisites" section
  313.      earlier in this document.
  314.        
  315.  
  316.    * Error Message: "Exception in thread NULL"
  317.      or "Unable to initialize threads: cannot find class
  318.      java/lang/Thread"
  319.  
  320.      If you are getting one of these fatal error messages
  321.      when running java, javac, or appletviewer, you should check
  322.      your CLASSPATH environment variable. If you are bypassing
  323.      the launch shell scripts in java/bin and using the executables
  324.      in java/bin/linux/native_threads then the CLASSPATH is not
  325.      being set correctly for the class libraries the tools need
  326.      to execute correctly.  You can set this at the shell prompt
  327.      as in the following example:
  328.  
  329.         $ export CLASSPATH=.:/usr/java/lib/classes.zip
  330.  
  331. _________________________________________
  332. RUNNING APPLETS WITH THE APPLETVIEWER
  333.  
  334. AppletViewer allows you to run one or more applets that are called by
  335. reference in a web page (HTML file) using the APPLET tag.  The
  336. AppletViewer finds the APPLET tags in the HTML file and runs the
  337. applets (in separate windows) as specified by the tags.
  338.  
  339. AppletViewer is for viewing applets.  It cannot display an entire
  340. web page that contains many HTML tags.  It parses only the APPLET
  341. tag and no other HTML on the web page.
  342.  
  343. To run an applet with appletviewer, you go to a command line for
  344. your operating system and run appletviewer, passing in the filename
  345. or URL of the web page as its argument.
  346.  
  347.   Here is an example of how to invoke AppletViewer on a file-based
  348.   web page under Linux.  Go to a shell prompt, change to the "/usr/java"
  349.   directory and then execute:
  350.  
  351.   ./bin/appletviewer myapplet.html
  352.  
  353.   Here is an example of how to invoke AppletViewer on a URL-based
  354.   web page under Linux. Execute:
  355.  
  356.   ./bin/appletviewer http://java.sun.com/applets/NervousText/example1.html
  357.  
  358. ______________________________________________
  359. DEBUGGING PROGRAMS WITH THE DEBUGGER (JDB)
  360.  
  361. You can debug applets using the -debug option of appletviewer.
  362. When debugging applets, it's best to invoke appletviewer from
  363. the directory that contains the applet's HTML file.  For example,
  364.  
  365.      cd demo/TicTacToe
  366.      ../../bin/appletviewer -debug example1.html
  367.  
  368. You can find documentation on the debugger and its API at:
  369.  
  370.      http://java.sun.com/products/jdk/1.1/debugging/
  371.  
  372.  
  373. _____________________________________
  374. Known Problems with the Alpha version
  375.  
  376.  
  377.  * Locale issues on RedHat Linux 6.0
  378.  
  379.    RedHat Linux 6.0 does not set the LANG variable for the 
  380.    current locale.  If this is not set correctly, certain 
  381.    Unicode characters are not displayed properly from 
  382.    the non-ASCII set of characters.  If you wish for this
  383.    to work properly, please set the LANG variable in
  384.    your shell before starting a Java application or applet.  For
  385.    example, the German locale can be set as follows:
  386.    
  387.     $ export LANG=de_DE
  388.     
  389.    The English/US locale can be set by performing:
  390.    
  391.     $ export LANG=en_US
  392.     
  393.    Even though certain locales may work using the LANG variable,
  394.    the alpha version of the IBM Developer Kit has not been tested on
  395.    any other locale except for English.
  396.    
  397.  * JRE exits unexpectedly when running an AWT application
  398.   
  399.    The JRE executable is included in this distribution for completeness,
  400.    however, at the current alpha level it has not been tested fully.
  401.    One known problem is that if you are running an AWT application that
  402.    is written such that the "main" method of the starting class creates
  403.    AWT objects and then exits, this will exit the jre, which will close
  404.    all the threads of the application and exit.  The jre does not have
  405.    this problem with non-AWT applications, such as a simple console
  406.    application.
  407.    
  408. -----------------------------------------------------------------------
  409. (c) Copyright IBM Corporation, 1999. All rights reserved.
  410. -----------------------------------------------------------------------
  411. Copyright ╕ 1996, 1997, 1998 Sun Microsystems, Inc.
  412. 901 San Antonio Rd., Palo Alto, CA 94303 USA
  413. All rights reserved.
  414. -----------------------------------------------------------------------
  415. *    IBM and alphaWorks are registered trademarks of International Business 
  416.       Machines Corporation.
  417. **   Java and all Java-based marks are trademarks or registered trademarks of 
  418.       Sun Microsystems, Inc. in the U.S. and other countries.
  419. *** All other company names may be trademarks or registered trademarks.
  420.  
  421.