IcedTea6
========

The IcedTea project provides a harness to build the source code from
openjdk.java.net using Free Software tools and dependencies.

IcedTea addresses two problems: it eliminates the build requirement on
proprietary build tools and it provides implementations of Java Web
Start and the browser plugin which are missing from OpenJDK.  It also
provides support for additional architectures via Zero/Shark or the
CACAO VM.

IcedTea also provides build scripts and patches that fix a number of issues
which are as yet unresolved upstream.

See INSTALL for build instructions.

Homepage (wiki):
  http://icedtea.classpath.org/

Bugs (bugzilla):
  http://icedtea.classpath.org/bugzilla

Mailing List: 
  distro-pkg-dev@openjdk.java.net
  http://mail.openjdk.java.net/mailman/listinfo/distro-pkg-dev

FAQ:
  http://icedtea.classpath.org/wiki/FrequentlyAskedQuestions

Anonymous Mercurial checkout:
  hg clone http://icedtea.classpath.org/hg/icedtea6

Java compatibility
------------------

IcedTea6 is derived from OpenJDK6, Oracle's open-source implementation of
the Java SE 6 platform and implements the Java SE 6 Platform
Specification.  Binaries produced by IcedTea6 have been known to pass
the TCK for Java 6.  IcedTea6 additionally provides autotools support,
plugin and Web Start support, ARM support, and a LLVM-based JIT
(Shark) for architectures beyond x86, x86_64 and SPARC, the
architectures supported by HotSpot JITs in OpenJDK6.

A Note About License Headers
----------------------------

Some sources downloaded from openjdk.java.net do not display the GPL
license header.  Instances are:

 - We are assuming that these files are owned by Sun:
   openjdk/jdk/src/share/classes/**/resources/*.properties

Web Browser Plugin support
===========================

IcedTea adds a browser plugin to OpenJDK.  IcedTea6 1.7 includes two
versions.  The default, and currently supported, version is a rewrite
called NPPlugin, developed to support recent Mozilla API changes.  It
is based on the old gcjwebplugin and has LiveConnect support.

The old plugin used by IcedTea6 1.6 and earlier is also included, but
will not work with xulrunner 1.9.2 and up.  You are welcome to use the
old plugin by supplying the --disable-npplugin option to configure,
but please note that such a configuration is no longer supported and
any bugs filed against it will be closed.

NetX
====

NetX provides a drop-in replacement for javaws (Java Web Start). Since
upstream NetX is dormant, we will be hosting and modifying the sources
in the IcedTea repository, particularly in the rt/net/sourceforge/jnlp
directory.

The NetX sources are built into rt.jar using the same method as
CORBA, JAXWS, JAXP and langtools.

IcedTea's NetX currently supports verification of signed jars, trusted
certificate storing, system certificate store checking, and provides
the services specified by the jnlp API.

The Zero Assembler and Shark Ports
==================================

Gary Benson has developed a port of the interpreter included in the
HotSpot virtual machine which avoids using any assembly language.  As
a pure C++ interpreter, it should be possible to build this on most
architectures and have a working (albeit slow) version of OpenJDK.
Successful builds have been made on ppc, ppc64 and arm.  The zero
assembler port is enabled by default on platforms other than x86,
x86_64 and sparc.  To enable it on these platforms, use the
--enable-zero option.

Gary is now working on a JIT called Shark to provide better
performance on platforms which need to use the zero port. A
preliminary version of this is now included with IcedTea and can be
built with the --enable-shark option.

CACAO as VM
===========

The CACAO virtual machine (http://cacaovm.org) can be used as an
alternative to the HotSpot virtual machine. One advantage of this is
that it already provides a JIT for many platforms to which HotSpot has
not yet been ported, including ppc, ppc64, arm and mips.  To use CACAO
as the VM, use the --with-cacao option.  This will download version
0.99.4 of CACAO during the build, which has been tested with this
version of IcedTea6.

The environment variable CACAO_CONFIGURE_ARGS can be used to pass
additional arguments to the cacao configure.

PulseAudio Mixer
================

Passing --enable-pulse-java to configure will build the PulseAudio Mixer for 
java. This allows java programs to use PulseAudio as the sound backend.

SystemTap Support
=================

The --enable-systemtap configure option will try to find the systemtap
runtime development files (sdt.h and the dtrace python script wrapper),
enable compilation of static markers in the hotspot code and install a
systemtap hotspot.stp tapset for easy tracing with systemtap's stap
utility. The probes are documented in tapset/hotspot.stp.

This requires the systemtap-sdt-devel package as build dependency and
optionally the systemtap package at run time when the user want to use
the tapset to trace java programs. The probes have zero overhead when
not used and can safely be compiled in even when not used at runtime.

Support for Additional VMs
==========================

Although IcedTea can be built multiple times to use a different virtual
machine, additional VMs can be built without building the other components
multiple times.

On architectures where hotspot is available, use 
   --with-additional-vms=cacao,zero  (or shark instead of zero)
on architectures where only zero (or shark) is available, use
   --with-additional-vms=cacao  
to build the additional VM's.  It's not possible to build cacao as the 
default VM, and zero as additional VM.

If the build was configured with --with-additional-vms, the additional VM's
are available by calling the java with the option `-cacao' or `-zero' (for
shark as well), or by calling the java tools with `-J-<vm name>'.