Debian Codegraph @

INSTALL

raw
1 D-Bus Java installation guide
2 -----------------------------
3
4 Prerequisites
5 -------------
6
7 To compile and install the library you will need:
8
9 A Java 1.5-compliant VM and Compiler (at time of writing
10 only the Sun VM and Compiler is known to work).
11 The unix socket, debug and hexdump libraries from http://www.matthew.ath.cx/projects/java/ (version 0.6 or later)
12 GNU gettext
13
14 To build and install the documentation you will also need:
15
16 A LaTeX environment
17 tex4ht
18 docbook
19
20 Compiling the Library
21 ---------------------
22
23 Simply invoke `make' in the top level directory to compile the library.
24 Depending on your JDK installation you may need to export JAVA_HOME
25 appropriately. The location of the unix-socket library can be set with
26 JAVAUNIXLIBDIR and JAVAUNIXJARDIR. Explicit paths to the javac, jar, java and
27 javadoc binaries can be set with the JAVAC, JAR, JAVA and JAVADOC variables.
28
29 The library will be installed into /usr/local by invoking `make install'. If
30 you wish to install them anywhere else then run make with the PREFIX variable
31 set to another location. More fine grained control of the installation
32 directories can be achieved using the BINDIR etc variables. For more detail
33 read the Makefile. DESTDIR can be used for packaging to install with the
34 correct hierarchy into a temporary folder.
35
36 NOTE: if you set PREFIX in `make install' you should also set it when invoking
37 just `make'. PREFIX is to create the binary wrappers with the correct paths to
38 the installed library.
39
40 Documentation for the library can be built with `make doc' and installed with
41 `make install-doc install-man', with the same provisos for installation paths.
42
43 Using the Library
44 -----------------
45
46 The documentation which is by default installed into
47 /usr/local/share/doc/libdbus-java/ gives detailed instructions on how to call
48 D-Bus programs using the Java implementation and a full API reference.
49
50 To run a Java program using D-Bus you need to have the libdbus-java,
51 libunix-java and libdebug jar files in your classpath and the libunix-java
52 shared library in your library path. With the default install paths you may
53 have to do something like:
54
55 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
56
57 Windows
58 -------
59
60 The Java D-Bus implementation can be used under Windows with TCP Sockets. There
61 are several windows batch scripts provided to ease use on Windows.
62
63 If the library is being compiled in a unix environment (including cygwin) the
64 normal Makefile can be used to create batch files under win/ with `make win'.
65 These batch files are wrapper scripts to run the included programs (DBusDaemon,
66 CreateInterface, ...) under windows. There is also a make target which creates
67 a zip file containing all the jars, wrapper scripts and dependency jars.
68
69 If you are compiling on windows there is a script, compile.bat, which will
70 create all the jars. You may have to alter the variables defined in it
71 depending where you have installed the dependencies and your Java compiler.
72 The other .bat files are the wrapper scripts which will need variables setting
73 appropriately before use.
74
75 Debugging
76 ---------
77
78 It is possible to enable debugging during the build. This will be a lot slower,
79 but can print a lot of useful information for debugging your program.
80
81 To enable a debug build compile with DEBUG=enable. This will then need to be
82 enabled at runtime by using the debug jar with debugging enabled (usually
83 installed as debug-enable.jar alongside the normal jar).
84
85 Running a program which uses this library will print some informative messages.
86 More verbose debug information can be got by supplying a custom debug
87 configuration file. This should be placed in the file `debug.conf' and has the
88 format:
89
90 classname = LEVEL
91
92 Where classname is either the special word `ALL' or a full class name like
93 `org.freedesktop.dbus' and LEVEL is one of NONE, CRIT, ERR, WARN, INFO, DEBUG,
94 VERBOSE, YES, ALL or TRUE. This will set the debug level for a particular
95 class. Any messages from that class at that level or higher will be printed.
96 Verbose debugging is extremely verbose.
97
98 In addition, the environment variable DBUS_JAVA_EXCEPTION_DEBUG will cause all
99 exceptions which are handled internally to have their stack trace printed when
100 they are handled. This will happen unless debugging has been disabled for that
101 class.