blob: bf0dbaae4bd72f43adfb96198be219101575b780 [file] [log] [blame]
This directory contains the Apache Harmony class library code.
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
* 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 for more
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
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 (
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
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.
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.
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 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 ...
+---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
+---boot <- common JARs for bootclasspath
+---ext <- extensions directory
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
<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 -*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 ( 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: 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/ 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/ file and then
running the ldconfig program to rebuild the /etc/
Linux users may need to update their GNU 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: *** [../] 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".
[javac] ----------
[javac] 1. ERROR in C:\dev\harmony\enhanced\classlib\trunk\modules\accessibi
lity\src\main\java\javax\accessibility\ (at line 0)
[javac] /*
[javac] ^
[javac] Internal compiler error
[javac] java.lang.OutOfMemoryError: Java heap space
[javac] ----------
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