README

This is the java-gnome language bindings project. We endeavour to provide a
high quality library you can use to write GTK and GNOME programs. The
underlying APIs are elegantly transformed into Java and carefully documented so
that anyone new to Linux or Open Source can rapidly be on their way to creating
fabulous applications.

<!--
If you didn't know, the project website is:  

	http://java-gnome.sourceforge.net

where we host the API documentation, web versions of all the design files, and
tutorials to help get people started. Contact information, release notes and
and project news are also to be found there.
-->

This README file is devoted to helping you get started building the bindings
themselves. 

Building java-gnome
===================

For the impatient:

    $ tar xjf java-gnome-4.0.6.tzr.bz2
    $ cd java-gnome-4.0.6
    $ ./configure
    $ make

But there's a bunch of stuff you probably want to know, so read on!


1. Get the source code
----------------------

### From a release tarball ###

You can download the latest java-gnome release from the GNOME FTP server at:  
[`http://ftp.gnome.org/pub/gnome/sources/java-gnome/4.0/`][mirror]

Once you've downloaded the latest source tarball:

    $ tar xjf java-gnome-4.0.6.tzr.bz2
    $ cd java-gnome-4.0.6

And go on to step 2 for details about options you can pass to the
configuration command.


### Or checkout the source ###

If you want a newer version of the code than the tarball you might have, you
can always check it out over the net. We use Bazaar (`bzr`), an advanced
third-generation Distributed Version [or Revision] Control System, to manage
our source code. 

Getting a checkout is easy:

    $ bzr init-repo java-gnome/
    $ cd java-gnome/
    $ bzr checkout bzr://research.operationaldynamics.com/bzr/java-gnome/mainline
    $ cd mainline/


2. Run `./configure`
--------------------

The top level directory contains a custom `./configure` which detects your
Operating System variant, sets defaults accordingly, verifies the location of
prerequisites (the various `.jar` files), and finally chooses a Java bytecode
compiler and Java Virtual Machine runtime environment. The configuration
output is a Makefile fragment which is written to `.config` and subsequently
included by the top level `Makefile`.

So run it already:

    $ ./configure

### Background ###

The steps necessary to configure and build a Java project are quite different
than those needed to construct a program written in a more traditional
language. Unlike C, for example, there is no need to do substitution across
the codebase nor to worry about conditional compilation; `#ifdef` is not
something we do in Java. This is in no small part because the Java class
libraries and the language itself have been remarkably stable. To build and
run a Java program, however, three things are necessary:

 * locate pre-requisite libraries (`.jar`s), and form a `CLASSPATH`;

 * locate, validate, and select a Java compiler; and

 * locate, validate, and select a Java runtime.

That's it! From there, often a single compiler invocation will take care of
building an entire program, but these preconditions must be satisfied before
compiling is possible. _(Incidentally, tools like Ant are no help with any of
this -- it just takes care of the build part; and don't even think about
suggesting the GNU autotools -- they are a complex, arcane, and bloated
nightmare that don't address with the Java specific challenges at all)_.

At the moment, we use Andrew Cowie's "Equivalence" build system, which is
composed of a straight-forward (if somewhat overweight) Perl program along
with a simple Makefile which together carry out the task of configuring and
building the library. Right now, Gentoo Linux, Debian Linux, Fedora Core
Linux, and Solaris Unix should be detected properly and result in working
configurations. If you are running a different operating system or
distribution, please contact us and we'll add it -- it's just a matter of
identifying the location of a few things. Better yet, look in the `configure`
Perl script -- the places where OS is switched are obvious, and just add what
you need to add, and send us a patch.

Hopefully in the not to distant future we will be able to switch to Robert
Collins's new "Buildtool". His approach to configuration and building will
revolutionize the Free and Open Source Software universe, and we look forward
to participating in the development of his work.

Meanwhile...

### Customizing build options ###

You can override the choices `configure` makes by listing parameters on the
command line, like this:

    $ ./configure compiler=ecj runtime=jamvm

This facilitates easily switching between runtimes and compilers for testing.
At the moment, the available selections are:

* `compiler` `-->` javac, ecj, and gcj -C

* `runtime`  `-->` java, cacao, jamvm, cacao, gij, and kaffe

The whole point of the Equivalence's `configure` script is to figure things
out for you, but if it can't quite figure out where Java is, you can override
it by specifying an alternate location to find a JDK using either
of the following:

* `jdk` -- where to find a traditional Java Development Kit, ie `JAVA_HOME`

* `gcj` -- prefix of an alternate GCC install

* `jamvm` -- path to the JamVM executable

* `cacao` -- path to the CACAO executable

Examples:

    $ ./configure
    $ ./configure jdk=/opt/sun-jdk-bin-1.5.0.13
    $ ./configure jamvm=/home/joe/custom/bin/jamvm runtime=jamvm

Your configuration is persistent across builds in that checkout, ie, `make
clean` won't force you to reconfigure (though `make distclean` will). The
`configure` script runs very quickly, so it's no big deal to switch settings
by re-running it.


3. Build
--------

Once you've configured, compiling java-gnome is as simple as running Make:

    $ make

If you're having trouble with something as Make runs and need to debug it, you
can try:

    $ V=1 make

This will show you the actual commands being executed (ie, Make's normal
behaviour, which we override for appearances sake and because otherwise the
signal to noise ratio is terrible and you never see warnings). If you're still
stumped, you might try having a look at `.config`, which is where all the Make
variables come from.

The build products end up in `tmp/`:

`tmp/gtk-4.0.jar`  
`tmp/libgtkjni-4.0.jar`

That's actually enough to go on -- if you're using an IDE like Eclipse you can
just tell it about the `.jar` and indicate that `tmp/` is the native library
location and you can jump right to "Using the Bindings". Or you can install
java-gnome somewhere. Doesn't matter, really.


4. Install
----------

java-gnome 4.0 has the standard `make install` behaviour, and the equally
standard `--prefix` option to `./configure`.

### Installing locally

Someone installing it locally (to your home directory, say) might do:

	$ ./configure --prefix=/home/bloggins
	$ make install

and you would end up with:

`~/share/java/gtk-4.0.jar`  
`~/share/java/gtk.jar`  
`~/lib/libgtkjni-4.0.so`

Of course, if you do that (or install anywhere else off the system shared
library search path), you'll need to use the `LD_LIBRARY_PATH` environment
variable or the `java.library.path` Java system property when you run programs
in order to tell your Virtual Machine where the library is. See below under
"Using the Bindings"

### Installing to system (for people packaging the library for their distro)

The `install` target understands the `DESTDIR` variable used by packagers to
install to a specified prefix _within_ a temporary directory. Someone writing
an `.ebuild` to create a package for java-gnome on a Gentoo system would
probably end up seeing the following commands being run by Portage, for
example:

	...
	
	./configure --prefix=/usr
	make
	
	...
	
	make DESTDIR=/var/tmp/portage/java-gnome-4.0.6-r2/image install
	
	...

With a prefix of `/usr` you will end up with

`/usr/share/java/gtk-4.0.jar`  
`/usr/share/java/gtk.jar`  
`/usr/lib/libgtkjni-4.0.so`

and maybe

`/usr/lib/libgtkjava-4.0.so`

If you have distro policy issues to deal with, then move things around once
they've landed in `DESTDIR`.

<a name="using"></a>

Using the bindings
==================

### Running the "demo"

There is a _tiny_ and _trivial_ demonstration program in the `tests/`
directory of the bindings. If you would like to see it, you could compile and
run it by hand, doing something like:

    $ javac -classpath tmp/gtk-4.0.jar -d tmp/classes tests/prototype/Experiment.java
    $ java -classpath tmp/gtk-4.0.jar:tmp/classes -Djava.library.path=tmp Experiment

This shows you how you can reference and use the library after it is built by
`make` into `tmp/`. Note the necessity to tell the VM where to find
java-gnome's JNI library.

Of course, that was _way_ too much typing. Instead, just do this:

    $ make demo

`:)`. As usual, use `V=1` to see what it is actually doing.

### Running your own programs

java-gnome has a native component that links tightly against various GNOME
libraries (after all, the whole point is to use the real GTK, not some pseudo
look alike pathetic attempt of a widget toolkit). This means that **you need
to tell Java where to find the native library in addition to the location of
the `.jar` file**. For instance:

    $ java                                           \
        -classpath /home/bloggins/share/java/gtk.jar \
        -Djava.library.path=/home/bloggins/lib       \
        -ea                                          \
        com.example.ComeOnBabyLightMyFire

Oh, the joys of running Java programs by hand. If you get an
`UnsatisfiedLinkError`, you've stuffed this part up. Go back and check that
you've actually got the java-gnome JNI library in the directory you specified.
Tip: for some reason, Java doesn't expand `~` in `java.library.path`. Go
figure.

If you're running programs in Eclipse, you can specify a native library
location in when you add a `.jar` file under  

> Project `->` Properties `->` Java Build Path

which can simplify your life a great deal. Just expand the entries under that
`.jar` and you'll see "Native library location: (none)". Enter the path to the
`lib` directory where you've got the `libgtkjni-4.0.so` file, and you're on
your way.

Status
======

java-gnome 4.0 is now a solid foundation that can be used to develop
non-trivial applications. The architecture and internal design has been well
proved, and the coverage level (relative to the full breadth of the underlying
libraries) is growing rapidly. The code generator which cranks out the project
internals (based on the shared metadata used by the other GNOME language
bindings) is in good shape and continuing to be refined.

Remember that java-gnome 2.x is completely deprecated and hasn't had new code
from anyone in years. You don't want to be programming with it. If it is still
available in your distribution, that's a bug.

Get Involved
------------

If you would like to get involved in 4.0 yourself as an individual, we would
welcome your contribution. See [`HACKING`](HACKING.html). If you are working
on an application, want to learn more, or are just curious, join us online in
`#java-gnome` on `irc.gimp.net`.

Funding
-------

Most of all, financial support is necessary to fund the continued development
of the bindings infrastructure and the programmers needed to quickly achieve
the coverage level everyone wishes. If you feel that you would like to be a
part of seeing the Java bindings for GNOME be a success, your timely choice to
contribute to funding the project would be a significant contribution to
bringing the wider Java community to the world of Open Source and Software
Freedom.

Happy coding!

AfC

`--`  
Andrew Frederick Cowie  
Managing Director,  
[Operational Dynamics](http://www.operationaldynamics.com/),  
a Change Management consultancy...

Maintainer,  
[java-gnome](http://java-gnome.sourceforge.net/),  
opening GTK and GNOME to Java programmers!

_Last modified 16 Mar 08_

[mirror]: http://ftp.gnome.org/pub/gnome/sources/java-gnome/4.0/

<!--

  Copyright (c) 2006-2008 Operational Dynamics Consulting Pty Ltd 

  As project documentation, this file forms an integral part of the source
  code of the library it accompanies, and thus is made available to you by the
  authors under the terms of the "GNU General Public Licence, version 2". See
  the LICENCE file for the terms governing usage, copying and redistribution.

  vim: set textwidth=78 nowrap:

-->
