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/wiki/IcedTea-Web

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 dead, we forked the code into the netx/net/sourceforge/jnlp package,
whole implementation is still in this package, NetX is kept referenced
However, as icedtea-web has evolved to complex set of tools, extensions and tests,
it has now only a few lines of code shared with the original implementation. 

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. 

In addition it also provides:
 * full desktop integration
 * offline run
 * own appletviewer
 * many extended security features
 * own policy editor and much more.
For full list read NEWS and Changelog

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-native-plugin option.

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

IcedTea-Web is built using the standard:

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

incantation.  The build requirements are as follows:

* A bootstrap JDK.  You can use any java JDK7 or higher compatible.
* A C compiler (for the launchers).

Additionally, the plugin requires:

* A C++ compiler
* npapi headers - depending on your distribution: firefox-devel or xulrunner-devel or NPAPI-SDK ...

Some distributions do not provide correct NPAPI headers so you can use those: 
https://bitbucket.org/mgorny/npapi-sdk/downloads.

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

The following optional dependencies enable additional features

* rhino (enables support for using proxy auto config files evaluating javascript)
* tagsoup (enables cleanup of not well formed JNLP files)
* junit4 (enables unit tests)
* jacoco (enables codecoverage)



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

Check IT_CHECK_FOR_JDK in acinclude.m4 to see the default search paths for JDKs.

At present, some of these options fail due to sun.* classes required
by IcedTea-Web.

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:

To configure jdk used for build and runtime, 
* --with-jdk-home and --with-jre-home are your best friends.
If you are using jdk without jre, it may force you to use  both those switches
to point to same location. 

* --disable-docs: Don't build the Javadoc documentation.
* --with-gcj: Compile ecj to native code with gcj prior to building. (deprecated)
* --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. (deprecated)
* --with-javac: Specify the location of a 'javac' binary.  By default, the path
  is checked for javac.  (deprecated)
* --with-jar: Specify the location of a 'jar' binary.  By default, the path
  is checked for gjar and jar. (deprecated)
 --with-ecj-jar: Specify the location of an ecj JAR file.  (deprecated)

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

* --disable-native-plugin: Don't build the browser plugin.
* --with-rhino: Specify the location of rhino jar
* --with-tagsoup: Specify the location of the tagsoup jar
* --with-jacoco: Specify the location of the jacoco jar

Rhino and Tagsoup 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.

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.

Tagsoup is used in similar way, and it is library used to fix malformed JNLP files.

Check acinclude.m4 to see the default search paths.

JUnit and Jacoco 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.

Jacoco is used in similar way and can be used to measure code-coverage both for
junit tests and for reproducer. For plugin a fake binary is created and used.

Check acinclude.m4 and Makefile.am to see the default behavior.

Testing
=======

A set of automated tests is supplied for IcedTea-Web. They can be run by using
'make check' or "make run-netx-dist-tests"
'make check' runs a set of unit tests are that always supposed to pass.
'make run-next-dist-tets' runs the reproducer test suite which requires
you to install IcedTea-Web first. (if you want to use it in your personal space,
use --prefix to specify final path)

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.
See http://icedtea.classpath.org/wiki/Reproducers for more.

For debugging, the environment variable ICEDTEAPLUGIN_DEBUG should be
set to 'true'. It also starts the debug server on port 8787. If you set it to
suspend  java will wait for debugger to join before launching main class.
You can set verbosity and logging levels via itweb-settings 
