Initial work on Java library.
[doldaconnect.git] / doc / INSTALL.applet
CommitLineData
ce515da4 1 GNOME Applet Installation
2
3Because of how GNOME works, special care is required when installing
4the transfer monitor applet. The problem lies in the fact that GNOME
5only looks for applets in certain directories, which usually does not
6/usr/local, whither Dolda Connect installs by default.
7
8A GNOME applet is a CORBA server, which must be found by GNOME's
9Bonobo activation daemon. By default, the Bonobo activation daemon
10looks in lib/bonobo/servers inside its own installation prefix. Since
11GNOME is usually installed in /usr, that would become
12/usr/lib/bonobo/servers on most systems, but it needs not necessarily
13be, and some systems have GNOME installed in /opt.
14
15Since the default prefix for autoconf programs such as Dolda Connect
16is /usr/local, the server description file installed by Dolda Connect
17will not be found by the Bonobo activation daemon. There are a number
18of ways to fix this:
19
201. Install Dolda Connect in /usr. This is ugly and not recommended,
21since /usr is normally reserved for programs shipped by the system
22maintainers. It does work, though, and it is easy. To do that, run
23./configure with a `--prefix=/usr' argument.
24
252. Move the applet files only to /usr after normal installation in
26/usr/local. This, too, is ugly and not recommended, but it might be
27considered slightly less ugly than #1, since the bulk of Dolda Connect
28still resides in /usr/local. To do that, move
29/usr/local/libexec/dolcon-trans-applet to /usr/libexec, and
30/usr/local/lib/bonobo/servers/Dolcon_Transferapplet_Factory.server to
31/usr/lib/bonobo/servers. Then, edit the latter file and replace every
32instance of /usr/local with /usr.
33
343. Add /usr/local to your system's GNOME prefixes. Doing so involves
35setting the environment variable GNOME2_PATH to include
36/usr/local. How to do that differs from system to system, and it is
37not possible for this document to contain information on how to do
38that on any given system. It is probably by far the best solution,
39however.
40
414. Add /usr/local to your user profile's GNOME prefixes. As above,
42this involves setting GNOME2_PATH to include /usr/local, but it is
43quite easy to do so in your own ~/.profile or ~/.bash_profile instead
44of editing the system-wide configuration. It is also the best idea if
45you have installed Dolda Connect in your own home directory rather
46than in /usr/local. Again, though, the exact steps to do this differs
47from system to system and also depend on what shell you use. It is
48extra noteworthy, however, that Ubuntu users may have rather severe
49problems with this [1].
50
51Remember, always after changing the system of user profile with
52regards to environment variables, you would need to log out and back
53in again to get the changes in all processes. It is of note, however,
54that the Bonobo activation daemon sometimes linger, and therefore does
55not get restarted when logging back in again. If this happens, just
56kill it (with `killall bonobo-activation-server'), and it will be
57restarted from a process having the correct environment.
58
59 Additional applet notes
60
61The applet is mostly working, but it still does have a few things that
62remain to be implemented. First of all, it only handles password-less
63authentication, so a setup using PAM will not work. Unix socket
64authentication, `authless' authentication and Kerberos V
65authentication all work, however. Last, there is no preference dialog
66to set which Dolda Connect server to connect to. If you run a local
67server using Unix sockets, it will not be a problem. Otherwise, you
68need to use the DCSERVER environment variable to specify which server
69to connect to.
70
71[1] See <https://bugs.launchpad.net/ubuntu/+bug/66004> for details.
72
73
74
75This document was last updated 2007-05-02, reflecting release 0.4 of
76Dolda Connect.