README

Project Caciocavallo - Portable GUI backends for OpenJDK
-----------------------------------------------------------

Introduction
------------

Caciocavallo - Portable GUI backends is one of the finalists of the
OpenJDK Innovators Challenge. As of March 17, 2008 (well, more or
less), Caciocavallo was selected as a finalist to the OpenJDK
challenge, so we even have a cool new website with nothing in it :)

http://openjdk.java.net/projects/caciocavallo/

Here is the mail with the original proposal:

http://mail.openjdk.java.net/pipermail/challenge-discuss/2008-March/000082.html

The project classified Bronze at the Challenge, giving us great honours and
proud :)

http://www.reuters.com/article/pressRelease/idUS134139+29-Sep-2008+BW20080929

You can find the interview with the original developes on this link:

http://mediacast.sun.com/users/robilad/media/daliboropenJDKwinners.ogg

The interview was conducted by a nice guy who's name is known by everyone in
the Free Java community, Dalibor Topic (robilad on IRC). Visit this link
for some other cool interviews:

http://robilad.livejournal.com/37607.html

A short presentation about Cacio was shoot at FOSDEM 2009 by Andrew John Hughes.
You can find it here:

http://www.jroller.com/neugens/entry/cacio_presentation_at_fosdem_2009

Good resource of information are the authors' blogs:

* http://kennke.org/blog/
* http://www.jroller.com/neugens
* http://weblogs.java.net/blog/thetan/

Checkout the code
-----------------

Ok, if you are reading this README chances are that you already got the sources
so you can skip this section.

In case you found this README somewhere else, the best way to get access
to the sources is to clone the main repository:

http://hg.openjdk.java.net/caciocavallo/ng/

Cacio used to have two repositories, so called internal (also called NG) and
external, as well as a number of patches we needed in order to make the project
work with OpenJDK; luckily these patches are all in the main OpenJDK
source tree now. All the repositories are not mantained anymore and are there
only for historical reasons (and because of the Challenge requirement,
of course).

Caciocavallo is no different than any other project in the OpenJDK forest, and
used Mercurial to manage it's sources. To get a fresh tree of sources just do:

$ hg clone http://hg.openjdk.java.net/caciocavallo/ng/ caciocavallo

If you don't specify the target directory it will create a default one called
ng, which is not really nice.

That's all for now, time to move on to...

Build
-----

Building Cacio requires OpenJDK7 or later, it will not work with any
previous release or alternative JDKs.

Caciocavallo utilizes Maven for the main modules. In the toplevel Cacio
directory simply type:

mvn clean install

This should compile Caciocavallo.

In order to build Cacio-web, you need an installation of Maven 2 (it will
not work with Maven3 ... yet). Go into the cacio-web subdirectory
and type:

mvn2 clean install

This should compile both the Java classes and native portions of Cacio-web.

The other, and as of now not supported, modules under the src/ directory utilize
Ant for building. Following is the old description of the Ant build process used
for those modules:

There is a build.properties file that needs tweaking with some paths, but this
file is tracked by Mercurial, so changing it will call for endless merge or
merge conflicts. As an alternative, you can create and edit user.properties in
the root directory of the project. This is handy because it's not tracked by
Mercurial.

Some of the interesting options are:

openjdk=/path/to/openjdk/build/
openjdk.src=/path/to/openjdk/sources
openjdk.build.generated.headers=/path/to/openjdk/generated/includes/

My file looks like:

openjdk=/home/neugens/work_space/netbeans/openjdk/build/linux-i586-debug
openjdk.src=/home/neugens/work_space/netbeans/openjdk
openjdk.build.generated.headers=/home/neugens/work_space/netbeans/openjdk/build/linux-i586-debug/tmp/

Just adjust with the correct paths on your configuration.

If you are not running under Linux, or you distribution uses some non
conventional paths (or for whatever other reason), you may need to change
this definition too:

sdl.include=/usr/include/SDL

This is needed only if you want to compile the libSDL backend.

To compile the native code, you need to provide ant with access to cpptasks:

http://ant-contrib.sourceforge.net/cpptasks/index.html

Something like:

CLASSPATH=/home/neugens/work_space/tools/cpptasks.jar ant compile

should do the trick.



Caciocavallo-Web
----

Caciocavallo-Web is a caciocavallo implementation for displaying AWT/Swing
applications in a html5 capable browser, while the application is runing
on a server. Events are sent from the browser to the server, 
whereas the visual output is sent to the browser.

Dependencies:

* JsKeyLib: Caciocavallo-Web requires a LGPL2 licensed javascript library for decoding
keyboard events, which because of licensing constraints can't be contained
in the caciocavallo-repository.
The library can be downloaded from: 
http://sourceforge.net/p/jskeylib/home/Home/

* Jetty-7 http://download.eclipse.org/jetty/
If you intend to use the WebSocket backend, please use the latest 
version of Jetty-8. Caciocavallo-Web has been tested successfully with 
jetty-8.0.1 (jetty-8.0 has a bug in session-handling which causes memory leaks).

* JUnit4 for running the unit tests.

* KeyPoint png encoder (optional)
For transports using the png format, keypoint's png encoder provides better
performance and allows to adjust the compressionLevel.
To enable the keypoint png encoder, simply download the library-file 
http://93.83.133.214/cacioweb/keypoint_png.jar
and add it to your classpath. (source file named keypoint_png_src.tar.gz)


Building:

Unzip jetty, and adjust the following paths in user.properties:
web.jetty_lib_dir=/home/ce/Development/libs/jetty
web.servlet-api=/home/ce/Development/libs/jetty/servlet-api-2.5.jar
web.jskeylib=/home/ce/jskeylib-code
lib.junit=/home/ce/Development/libs/junit-4.8.2.jar

Use the following ant-task to build the server runtime: cacio.web.srv-runtime

To start the application, simply add the application you would like to run
to the classpath, add the native part to the java_library_path and start the server runtime:
java -cp cacio-web-runtime.jar:SwingSet2.jar:(keypoint_png.jar) 
-Djava.library.path=build/web/lib/ net.java.openjdk.cacio.server.CacioServer

and open the ApplicationStarter-Servlet using your Browser:
http://localhost:8080/SessionInitializer?cls=SwingSet2

It is also possible to specify a compression format, when starting 
an Application: http://localhost:8080/SessionInitializer?cls=SwingSet2&format=png

When using png-compression, the compression-level can be adjusted additionally:
http://localhost:8080/SessionInitializer?cls=SwingSet2&format=png&clevel=2
where cLevel can be an integer between 0 (no) and 9 (highest) compression.


Test
----

[TODO]

It's pretty much everything for now, but stay tuned for other cool
stuff :)