Building IcedTea6
=================

For convenience we've provided make targets that automatically
download, extract and patch the source code from openjdk.java.net, in
a default location.

The build requirements are as follows:

GNU libgcj 4.3.0 (or equivalent 1.5 class library, such as GNU Classpath >= 0.95)
Eclipse Java Compiler
CUPS
libX11 (libXp, libXtst, libXi, libXt)
Freetype2
patch
sed
tar
md5sum
wget
alsa
xalan
xerces
firefox-devel 
glib2-devel 
gtk2-devel
ant >= 1.6.5
libXinerama-devel
giflib-devel
libpng-devel
libjpeg-devel = 6b
zlib-devel
rhino (can be disabled using --without-rhino)

For building the PulseAudio based mixer, you will need
pulseaudio-libs-devel >= 0.9.11
pulseaudio >= 0.9.11

For building VisualVM, you will need
netbeans = 6.5

For building the zero-assembler port (see below), you will need libffi.

For building with systemtap support (--enable-systemtap), you will need
systemtap-sdt-devel (available since systemtap 0.9.5). This also needs
the --with-abs-install-dir configure option to make sure the hotspot.stp.in
tapset gets the correct installation location for the libjvm.so, it
defaults to the root of the j2sdk-image build dir otherwise (but then
you cannot move that to another location without adjusting the paths
in the tapset/hotspot.stp file. For example:
 --enable-systemtap --with-abs-install-dir=/usr/lib/jvm/java-1.6.0-openjdk
(Java method tracing works starting with systemtap 0.9.9)

See ./configure --help if you need to override the defaults.

To bootstrap IcedTea with ecj:
autoreconf
./configure 
make

To build IcedTea with an older version of IcedTea, use:
autoreconf
./configure --with-icedtea 
	[default location: /usr/lib/jvm/java-icedtea, 
		to specifiy location use --with-icedtea-home=/path/to/icedtea]
make

There is currently no install target.

IcedTea ends up in openjdk/control/build/<os>-<arch> when the build completes.
Example instantiations of <os>-<arch> include linux-i586, linux-amd64 and linux-ppc64.

Rebuilding The IcedTea Plugs
----------------------------

When IcedTea is initially built, it creates stamp files in the stamps directory
to determine what and when dependencies were compiled. For example, to rebuild 
the rt plugs certain files need to be deleted before restarting the build.

 - If the rt plugs have been modified, delete stamps/rt-class-files.stamp.
 - If a new class has been added to the rt plugs, delete
 rt-source-files.txt  so it can be recreated with the new class list.

To view all targets that create stamp files, see 
Makefile.am (section 'All Stamped Targets').

The Zero Assembler Port
-----------------------

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
-----

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 CACAO
0.99.3 during the build.  To use a different version, use
--with-cacao-home=<dir> to point to an existing installation which use
the Sun VM interface.

Building additional virtual machines
------------------------------------

Although IcedTea can be built multiple times to use a different virtual
machine, addtional VM's 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.

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>'.

Support for different versions of HotSpot
----------------------------------------- 

IcedTea allows the version of HotSpot provided with the upstream build
drop to be replaced with another.  Support this is provided by the
--with-hotspot-build option which causes IcedTea to probe the
hotspot.map file for an entry with the given build name.  The
hotspot.map file maps the name to a changeset from the repository
http://hg.openjdk.java.net/hsx/hsx14/master/ which it downloads from
http://hg.openjdk.java.net/hsx/hsx14/master/archive/${CHANGESET}.tar.gz.
The resulting download is verified using the MD5 sum stored in
hotspot.map.

New build selections may be provided by providing further mappings in
the hotspot.map file.  The name can be anything
e.g. 'shiny_new_hotspot'.  This is simply used to map the argument to
--with-hotspot-build to the values in the file and to apply
appropriate patches (see patches/hotspot, $HSBUILD is available in
Makefile.am for obtaining the build name).  The special value
'original' is used to denote the upstream HotSpot and does not appear
in hotspot.map.  The changeset should map a valid changeset in the
HotSpot Express master repository (URL shown above).  These can be
obtained from a local checkout or using the web interface.  The
simplest way to calculate the MD5 sum is to download the tarball and
then run the 'md5sum' application on it.  The resulting value should
be added to hotspot.map.

As with the OpenJDK build tarballs, the location of an alternate zip
can be specified using --with-hotspot-src-zip.  This skips the
download stage and just verifies that the zip's MD5 sum matches that
of the requested build.

At present, the build name 'default' is used in hotspot.map to provide
the latest version of HotSpot 14 in place of the version of HotSpot 11
provided by upstream.  Thus, --with-hotspot-build is enabled by
default, and either --without-hotspot-build or
--with-hotspot-build=original is required to revert to the upstream
HotSpot.