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