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

For building VisualVM, you will need
netbeans = 6.5

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

For building the Shark JIT, you will need LLVM 2.5 or current SVN.

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 and a Classpath-based JDK such as GCJ:
autoreconf
./configure 
make

To build IcedTea with an older version of IcedTea or OpenJDK, use:
autoreconf
./configure --with-openjdk 
	to specify the location use --with-openjdk=/path/to/icedtea]
make

There is currently no install target.

IcedTea ends up in openjdk/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.
To build zero as the default VM and shark as an additional VM, use
   --enable-zero --with-additional-vms=shark

The additional VM's are available by calling the java with the option
`-cacao', `-zero' or `-shark', or by calling the java tools with
`-J-<vm name>'. If the build was configured with '--enable-shark',
use `-Xint' to just use the zero VM.

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

IcedTea allows the version of HotSpot provided with the upstream build
drop to be replaced with another.  Support for 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 a given repository
URL.  During the build, it downloads HotSpot from
${URL}/archive/${CHANGESET}.tar.gz and the resulting file 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 for patches/hotspot/original to denote those for
the upstream HotSpot; this value does not appear in hotspot.map.  

The changeset and URL should refer to a valid HotSpot tree when used
as above.  The required values can be obtained from a local checkout
or by 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, two versions of HotSpot are officially supported.  These
are HotSpot 14 ('original') which is provided by the upstream OpenJDK
tarball, and 'hs16', which is used in hotspot.map to provide the
latest version of HotSpot 16.  Thus, either --with-hotspot-build
without an argument or --with-hotspot-build=hs16 provides the
latest supported hs16, while no HotSpot build argument,
--without-hotspot-build or --with-hotspot-build=original uses the
upstream HotSpot.