igraph library Java interface
=============================

Preface
-------

**ATTENTION**: This is a highly experimental, proof-of-concept Java interface.
Its main purpose was to convince me that it can be done in finite time :)
The interface is highly incomplete, at the time of writing even some
essential functions (e.g. `addEdges`) are missing. Since I don't use Java
intensively, chances are that this interface gets finished only if there
is substantial demand for it and/or someone takes the time to send patches
or finish it completely.

Requirements
------------

In order to compile the Java interface from scratch, you'll need the
following:

* A recent C compiler

* A recent Java SDK (>= 1.5)

* Python 2.4 or later if you want to use the interface generator called
  Stimulus (found in tools/stimulus.py in the igraph distribution) to
  generate `src/Graph.java` and `src/net_sf_igraph_Graph.c`

* A GNU-compatible environment (e.g. Cygwin or MinGW on Windows,
  practically anything on Linux, XCode Developer Tools on Mac OS X)

* The `Apache Ant build tool <http://ant.apache.org>`_ for Java

* `ant-contrib.jar` and `cpptasks.jar` somewhere in your Ant path.
  You can get these from http://ant-contrib.sourceforge.net.

* JUnit 4 if you want to run the unit tests. You can get it from
  http://junit.org. Put the downloaded JAR file in the `lib`
  subdirectory and rename it to `junit.jar`.


Compilation steps
-----------------

First, compile and install the C core of igraph (see the corresponding
[documentation](http://igraph.org). After that,
change to `interfaces/java` and type `ant build`.
This should generate two files in the `dist/` subdirectory:

* `igraph-0.6.jar` (substitute the appropriate version number of course).
  This contains the platform-independent compiled class files. Put it
  wherever you want in your classpath.
    
* `igraph-java-wrapper.dll` on Windows, `libigraph-java-wrapper.so` on
  Linux or `libigraph-java-wrapper.jnilib` on Mac OS X. This contains the
  platform-dependent parts. Put it somewhere in the Java library path
  so Java can find it. (The library path can be determined by
  `System.out.println(System.getProperty("java.library.path"))` from
  Java. If you want to keep it elsewhere, you can alter the library
  path by passing `-Djava.library.path=whatever` to the Java
  interpreter when executing an igraph-based program.
  
`ant` might fail stating that igraph is not installed on your
system. In that case, you must specify explicitly where igraph is
to be found by tweaking the appropriate properties in `build.xml`.

Bugs, suggestions
-----------------

Drop me a mail at <tamas@cs.rhul.ac.uk> if something sucks. Contact
me also if you find this a great idea and want to complete it for
the benefit of the whole open source community :)
