README
======


This directory contains the Apache Harmony class library code.


Contents
--------
After checking out the code onto disk at <EXTRACT_DIR> you should find the
following directories under <EXTRACT_DIR> :

*  make     - support for building the source code and packaging the results.

*  depends  - support files (both text and binary) that are required to build
              the class libraries and any native libraries required. Includes
              several third party source files as detailed in the file
              Harmony/depends/oss/README.txt.
               
*  doc      - configuration files and images that are required to generate
              HTML documentation of the Java and C source using the Doxygen
              documentation system. Pre-genenerated HTML is included. 
               
*  modules  - Java, C/C++, assembly source files that can be compiled into the
              class library component files.

*  support  - Java source files used to support test cases across various modules.


Export Notice
-------------

This distribution includes cryptographic software.  The country in 
which you currently reside may have restrictions on the import, 
possession, use, and/or re-export to another country, of 
encryption software.  BEFORE using any encryption software, please 
check your country's laws, regulations and policies concerning the
import, possession, or use, and re-export of encryption software, to 
see if this is permitted.  See http://www.wassenaar.org/ for more
information.

The U.S. Government Department of Commerce, Bureau of Industry and
Security (BIS), has classified this software as Export Commodity 
Control Number (ECCN) 5D002.C.1, which includes information security
software using or performing cryptographic functions with asymmetric
algorithms.  The form and manner of this Apache Software Foundation
distribution makes it eligible for export under the License Exception
ENC Technology Software Unrestricted (TSU) exception (see the BIS 
Export Administration Regulations, Section 740.13) for both object 
code and source code.

The following provides more details on the included cryptographic
software:

Apache Harmony contains code that is specifically designed to enable
cryptography.  In particular Apache Harmony contains an implementation
the Java cryptographic extensions.  In addition, binary distributions
of Apache Harmony may contain cryptographic functionality provided by
The Legion of the Bouncy Castle (http://www.bouncycastle.org).


Pre-requisites for Building
---------------------------
In order to build the source code contained in the modules and support
directories, it is necessary to configure the following tools in the user 
environment. That is, the working environment should be such that the PATH 
environment variable contains all of the directories where the executables of
the tools listed below are located and that all of those executables can be 
successfully invoked from the command line.


* C compiler - on Windows, the Microsoft(R) 32-bit C/C++ Compiler and on
               Linux, the GNU project C/C++ Compiler.

* Java compiler - By default, the build scripts are setup to use the Eclipse
                  compiler (ECJ). The ECJ needs to be in the Ant class path
                  to execute correctly. The ECJ JAR is downloaded when the 
                  'fetch-depends' target is run on the top-level build script.
                  Once downloaded copy the JAR from HARMONY_TRUNK/depends/ecj_x.x
                  folder to the ANT_HOME/lib folder.
                  
* Apache Ant - A Java based build tool. See http://ant.apache.org/.
               It's suggested that the ANT_OPTS environment variable be set
               to a value of "-Xms256M -Xmx512M" while running the build scripts
               for Harmony.

* Doxygen - the open source documentation system for a variety of programming 
            languages including C, C++ and Java.
            See http://www.doxygen.org
            

The top-level Ant script <EXTRACT_DIR>/build.xml has a default target 
which builds both the Java source and C source files. It is expected
therefore that, at a minimum, a C compiler and a Java compiler be available.
Doxygen is only necessary if generation of HTML documentation from the
source code is to be carried out by invoking Ant with the "doc" target on
the <EXTRACT_DIR>/build.xml script. As a convenience, pre-generated
HTML files are already stored in subversion.



Building
--------
The simplest way to get started is to change directory into <EXTRACT_DIR> and
then type "ant" to run Apache Ant against the default target of the build.xml
file. Provided that the required compilers are available, Ant will proceed to
compile all the class library source code.


Building Java
-------------
The class files output from the Java compilation will be assembled into a set
of JAR files which reflect the components of the class libraries (see
http://wiki.apache.org/harmony/ClassLibrary for more information). Together with
the required support files, these JAR files will then be laid out in the boot
directory of the following directory tree structure ...

<EXTRACT_DIR>
       |
       \---deploy
             |
             \---jdk
                  |
                  \---jre
                       |
                       +---bin           <- classlibrary native code & launcher
                       |   |
                       |   +---default   <- VM-specific files for launcher's default VM
                       |   +---vm1       <- VM-specific files for 'vm1'
                       |   \---vm2       <- VM-specific files for 'vm2', and so on
                       |
                       \---lib
                           |
                           +---boot      <- common JARs for bootclasspath
                           | 
                           +---ext       <- extensions directory
                           |
                           \---security
    


Building Natives
----------------
Next, the source files contained under <EXTRACT_DIR>/modules will be
built using the available C/C++/ASM compiler. The output from this stage will be the 
creation of a launcher executable (java.exe on Windows, java on Linux) in the 
bin directory of the above layout together with a number of shared libraries
(with the .dll extension on Windows, and .so on Linux). 

On Windows if the native build exits with the message :

fatal error U1052: file 'ntwin32.mak' not found

this is an indication that the required build environment has not been properly
configured in the working console window. 



Build Output
------------
The supplied source is built into a set of Java class libraries and the native 
shared libraries necessary to support their correct functioning. In order to 
be used to run a compiled Java application the built class libraries still
require a virtual machine component. 



Building Documentation
----------------------
Two sets of HTML files can be found under the <EXTRACT_DIR>/doc directory. 

* kernel_doc - contains HTML documentation on the set of Java classes called the
               "kernel classes". These are the set of classes which - under the
               Harmony class library architecture - are closely tied to
               the structure of the VM. 
               Browse <EXTRACT_DIR>/doc/kernel_doc/html/index.html

* vm_doc - contains HTML documentation concerned with how the Java class
           libraries may be used on different VM implementations. This includes
           an overview of the external dependencies of the class libraries 
           and introduces a VM interface through which the class library natives
           and VM can interoperate with one another.        
           Browse <EXTRACT_DIR>/doc/vm_doc/html/index.html

Running the "doc" target of the top-level Ant script
<EXTRACT_DIR>/build.xml will refresh the contents of these directories.
The target makes use of the doxygen tool and so expects the doxygen executable
to be available in the current user environment (i.e the user PATH environment
variable should contain an entry for <DOXYGEN_INSTALL_DIR>/bin ). 



Modifying the Java Build Compiler
---------------------------------
By default, the Java compiler is set to use the ECJ compiler. This value is
set in the HARMONY_TRUNK/make/properties.xml and looks like the following XML
element.

<property name="hy.javac.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter" />

The compiler can be set to "modern", as per the Ant manual, which will cause Ant
to use the JDK's 'javac' tool. You may also need to change the 'build.compilerarg'
to '-nowarn' instead of the JDT '-warn:none'.


Options for ECJ compiler
------------------------

For more information on configuring the ECJ, check out this document on the batch
compiler - http://dev.eclipse.org/viewcvs/index.cgi/*checkout*/jdt-core-home/howto/batch%20compile/batchCompile.html?rev=HEAD&content-type=text/html.


What's Next ?
-------------

The class libraries do not provide the full JSE API. Instead the included source
is only a subset of the Java 1.5 API.


To test out the functionality of the built class library components a compatible
VM needs to be obtained.  A compatible VM implements the Virtual Machine Interface
as described in the documentation above.


Troubleshooting & Known Problems
--------------------------------

Linux users may need to install an appropriate libc compatibility patch to their
operating system if they see the following error message when attempting to run
a Java application with the built class library components on a compatible VM :

<error: unable to load ICUInterface34 (libstdc++.so.5: cannot open shared object
file: No such file or directory)>

Where to obtain the required patch and the precise means of applying it will 
obviously differ according to Linux distribution. On Debian the advanced package
tool apt-get could be used as follows :

user@server:~$> apt-get install libstdc++5

On a Red Hat Enterprise Linux machine the rpm tool may be used to install the 
equivalent package thus : 

user@server:~$> rpm -Uvh compat-libstdc++-33-3.2.3-47.3.i386.rpm

Consult the system administration documentation of your particular Linux
distribution for more information.

                                  ----------

Linux users may need to update the value of their LD_LIBRARY_PATH environment 
variable if they see the following error message when attempting to run a Java
application with the built class library components on a compatible VM : 

error while loading shared libraries: libhyprt.so: cannot open shared 
object file: No such file or directory

On some systems this error can occur even when the shared library
(e.g. <EXTRACT_DIR>/deploy/jdk/jre/bin/libhyprt.so) has been built correctly
and is present in the correct location. This is not a problem with the built
shared library but instead is dependent on how the operating system locates and 
loads dynamically linked libraries at runtime. Updating the LD_LIBRARY_PATH 
environment variable to include the directory
<EXTRACT_DIR>/deploy/jdk/jre/bin should solve this. An alternative remedy 
would be to add new entries for each of the shared libraries built from the
contributed native source code to the local /etc/ld.so.conf file and then 
running the ldconfig program to rebuild the /etc/ld.so.cache. 

                                  ----------

Linux users may need to update their GNU Make (http://www.gnu.org/software/make/)
to version 3.80 or later if they see the following error message when attempting
to build native source:

: No such file or directory
make: *** [../libvmi.so] Error 1

(The library name may be different)

                                  ----------

If the build fails with an odd error that similar to the following output snippet,
try setting the ANT_OPTS environment variable to "-Xms256M -Xmx512M".

<snippet>
    [javac] ----------
    [javac] 1. ERROR in C:\dev\harmony\enhanced\classlib\trunk\modules\accessibi
lity\src\main\java\javax\accessibility\Accessible.java (at line 0)
    [javac]     /*
    [javac]     ^
    [javac] Internal compiler error
    [javac] java.lang.OutOfMemoryError: Java heap space

    [javac] ----------

BUILD FAILED
C:\dev\harmony\enhanced\classlib\trunk\build.xml:108: The following error occurr
ed while executing this line:
C:\dev\harmony\enhanced\classlib\trunk\make\build-java.xml:143: java.lang.reflec
t.InvocationTargetException
</snippet>