source: trunk/icedtea-web/README@ 425

IcedTea-Web
===========

The IcedTea-Web project provides a Free Software web browser plugin
for running applets written in the Java programming language and an
implementation of Java Web Start, originally based on the NetX
project.

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/icedtea-web

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-Web repository, particularly in the netx/net/sourceforge/jnlp
directory.

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 Browser Plugin
==================

IcedTea-Web contains a Free Software browser plugin based on NPRuntime
called NPPlugin.  By default, this will be built, and it can be turned
off using the -disable-plugin option.

Building IcedTea-Web
====================

IcedTea-Web is built using the standard:

$ ./autogen.sh (if building from Mercurial rather than a tarball)
$ ./configure
$ gmake
$ gmake install

incantation.  The build requirements are as follows:

* A bootstrap JDK.  At present, only IcedTea6 is supported.
* A C compiler (for the launchers).
* libX11
* zlib-devel

Additionally, the plugin requires:

* A C++ compiler
* firefox-devel 
* xulrunner-devel

The plugin can be disabled by passing --disable-plugin.

The following optional dependencies enable additional features

* rhino (enables support for using proxy auto config files)
* junit4 (enables unit tests)

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

The following locations are checked for a JDK:
    * /usr/lib/jvm/java-openjdk
    * /usr/lib/jvm/icedtea6
    * /usr/lib/jvm/java-6-openjdk
    * /usr/lib/jvm/openjdk
    * /usr/lib/jvm/java-icedtea
    * /usr/lib/jvm/java-gcj
    * /usr/lib/jvm/gcj-jdk
    * /usr/lib/jvm/cacao
in the order given above.  

At present, some of these options fail due to sun.* classes required
by IcedTea-Web.  Upstream OpenJDK will only be able to compile
IcedTea-Web if the patch applet_hole.patch from IcedTea has been
applied.

Most targets in IcedTea-Web create stamp files in the stamps directory
to determine what and when dependencies were compiled.  Each target
has a corresponding clean-x target which removes the output and the
stamp file, allowing it to be rebuilt.

Build Modification Options
==========================

The build process may be modified by passing the following options
to configure:

* --disable-docs: Don't build the Javadoc documentation.
* --with-gcj: Compile ecj to native code with gcj prior to building.
* --with-ecj: Specify the location of a 'ecj' binary.  By default, the path
  is checked for ecj, ecj-3.1, ecj-3.2 and ecj-3.3.
* --with-javac: Specify the location of a 'javac' binary.  By default, the path
  is checked for javac.
* --with-jar: Specify the location of a 'jar' binary.  By default, the path
  is checked for gjar and jar.
* --with-ecj-jar: Specify the location of an ecj JAR file.  By default, the
  following paths are checked:
    - /usr/share/java/eclipse-ecj.jar
    - /usr/share/java/ecj.jar
    - /usr/share/eclipse-ecj-3.{2,3,4,5}/lib/ecj.jar

Other options may be supplied which enable or disable new features.
These are documented fully in the relevant section below.

* --disable-plugin: Don't build the browser plugin.
* --with-rhino: Specify the location of rhino jar
* --with-junit: Specify the location of the junit 4 jar

Rhino Support
=============

IcedTea-Web needs rhino for using Proxy Auto Config (PAC) files. If rhino is
not found, or explicitly disabled, then support for PAC files will be disabled.

By default, the following paths are checked for rhino:
  - /usr/share/java/js.jar
  - /usr/share/rhino-1.6/lib/js.jar
  - /usr/share/java/rhino.jar

If a rhino jar is not found, rhino support is disabled. The --with-rhino build
option can be used to specify the location of the jar file. To explicitly
disable rhino use --with-rhino=no.

JUnit Support
=============

JUnit is needed for running some tests. It has no run-time impact.

By default, the following paths are checked:
  - /usr/share/java/junit4.jar

If JUnit is not found, JUnit support is disabled. The --with-junit option can
be used to specify the location of the JUnit 4 jar. To disable JUnit support
explicitly, use --with-junit=no.

A custom JUnit ouput formatter is supplied. This makes the output of JUnit
tests match the output of other tests. A simple 'Passed:' or 'FAILED:' is
printed out, followed by <TestClass>.<testMethod>. This is also the format used
by JTreg.

Testing
=======

A set of automated tests is supplied for IcedTea-Web. They can be run by using
'make check'. Currently, this only tests a few parts of IcedTea-Web.

The number and type of tests run by 'make check' may be affected by the build
options, including JUnit support and rhino support.

A test suite is supplied for the browser plugin.  It can be built
using 'make plugin-tests' and run by loading the HTML page specified
into a browser with the plugin installed.

For debugging, the environment variable ICEDTEAPLUGIN_DEBUG should be
set to 'true'.  This will produce output on the console from the C++
side, and output from the Java side in $HOME/.icedteaplugin/java.stdout
and $HOME/.icedteaplugin/java.stderr.  It also starts the debug server
on port 8787.