documentation and changing binding to implementation

1 files changed, 49 insertions, 21 deletions

diff --git a/INSTALL b/INSTALL
index 6f16321..a033d42 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,15 +1,14 @@
-D-Bus Java bindings installation guide
----------------------------------------
+D-Bus Java installation guide
+-----------------------------
 
 Prerequisites
 -------------
 
-To compile and install these bindings you will need:
+To compile and install the library you will need:
 
    A Java 1.5-compliant VM and Compiler (at time of writing
          only the Sun VM and Compiler is known to work).
-   A C compiler and toolchain.
-   D-Bus 1.0 libraries
+   The unix socket, debug and hexdump libraries from http://www.matthew.ath.cx/projects/java/
 
 To build and install the documentation you will also need:
 
@@ -17,38 +16,67 @@ To build and install the documentation you will also need:
    tex4ht
    docbook
 
-Compiling the Bindings
-----------------------
+Compiling the Library
+---------------------
 
-Simply invoke `make' in the top level directory to compile the bindings.
+Simply invoke `make' in the top level directory to compile the library.
 Depending on your JDK installation you may need to export JAVA_HOME
-appropriately. 
+appropriately. The location of the unix-socket library can be set with
+JAVAUNIXLIBDIR and JAVAUNIXJARDIR. Explicit paths to the javac, jar, java and
+javadoc binaries can be set with the JAVAC, JAR, JAVA and JAVADOC variables.
 
-The bindings will be installed into /usr/local by invoking `make install'.  If
+The library will be installed into /usr/local by invoking `make install'.  If
 you wish to install them anywhere else then run make with the PREFIX variable
 set to another location. More fine grained control of the installation
 directories can be achieved using the BINDIR etc variables. For more detail
-read the Makefile. DESTDIR can be used for packaging to install with the correct hierarchy into a temporary folder.
+read the Makefile. DESTDIR can be used for packaging to install with the
+correct hierarchy into a temporary folder.
 
 NOTE: if you set PREFIX in `make install' you should also set it when invoking
 just `make'. PREFIX is to create the binary wrappers with the correct paths to
 the installed library.
 
-Documentation for the bindings can be built with `make doc' and installed with
+Documentation for the library can be built with `make doc' and installed with
 `make install-doc install-man', with the same provisos for installation paths.
 
-Using the Bindings
-------------------
+Using the Library
+-----------------
 
 The documentation which is by default installed into
 /usr/local/share/doc/libdbus-java/ gives detailed instructions on how to call
-D-Bus programs from Java using these bindings and a full API reference.
+D-Bus programs using the Java implementation and a full API reference.
 
-To run a Java program using D-Bus you need to have the libdbus-java jar file in
-your classpath and both the libdbus and libdbus-java shared object files in
-your library path. With the default install paths you may have to do something
-like:
+To run a Java program using D-Bus you need to have the libdbus-java,
+libunix-java and libdebug jar files in your classpath and the libunix-java
+shared library in your library path. With the default install paths you may
+have to do something like:
 
-java -cp /usr/local/share/java/dbus.jar -Djava.library.path=/usr/lib:/usr/local/lib/jni
+java -cp /usr/local/share/java/dbus.jar:/usr/local/share/java/unix.jar:/usr/local/share/java/debug-disable.jar -Djava.library.path=/usr/local/lib/jni
 
-You may also have to export LD_LIBRARY_PATH=/usr/lib:/usr/local/lib/jni
+Debugging
+---------
+
+It is possible to enable debugging during the build. This will be a lot slower,
+but can print a lot of useful information for debugging your program.
+
+To enable a debug build compile with DEBUG=enable. This will then need to be
+enabled at runtime by using the debug jar with debugging enabled (usually
+installed as debug-enable.jar alongside the normal jar).
+
+Running a program which uses this library will print some informative messages.
+More verbose debug information can be got by supplying a custom debug
+configuration file. This should be placed in the file `debug.conf' and has the
+format:
+
+classname = LEVEL
+
+Where classname is either the special word `ALL' or a full class name like
+`org.freedesktop.dbus' and LEVEL is one of NONE, CRIT, ERR, WARN, INFO, DEBUG,
+VERBOSE, YES, ALL or TRUE. This will set the debug level for a particular
+class. Any messages from that class at that level or higher will be printed.
+Verbose debugging is extremely verbose.
+
+In addition, the environment variable DBUS_JAVA_EXCEPTION_DEBUG will cause all
+exceptions which are handled internally to have their stack trace printed when
+they are handled. This will happen unless debugging has been disabled for that
+class.