INSTALLING tp4d & friends
=========================

PREREQUISITES:
--------------
 - notebook computer with trackpoint device
   (mine is a ThinkPad 600E).
   To find out if your trackpoint may work use the following
   procedure:

   On a first virtual console (DONT USE X OR GPM or any similar) issue:

     dd if=/dev/psaux bs=1b count=3 | od -tx1

   then, switch to a second virtual console (still no X etc.). There you
   issue

     echo -n \\0341 > /dev/psaux

   and switch back to first VT. If you see no output there, or if the
   first two bytes of the od output are not: 0xfa 0x01, it's likely
   that your trackpoint is not supported. However, you must be VERY
   CAREFUL not to touch the trackpoint while doing this check (it will
   maybe produce output and mess up the detection. Maybe you should try
   more than once).

   NOTE: it is a good idea to test the shell escaping of the 'echo' command:
   use something like 'echo \\101' which should print a 'A' character.
   Make sure you understand your shell and echo command's escape syntax.
   (some echos [e.g. shell builtins] cannot handle \xxx at all, others
   need a -e option etc.)
   
   However, don't forget that this check is only a quick-hint; it's
   better to continue and test `tp4d' itself.

 - LINUX 2.2
   (I currently have SuSE 6.1 / 6.4 installed)
   you should have APM support in the kernel.
 - libapm.a

 for the xtp4 client, you need also

 - libXpm (optional)
 - libXaw3d

INSTALLATION (quick - for the impatient) 
----------------------------------------

 - unzip/untar
 - xmkmf -a
 - make
 - make install (as superuser)
 - make install.man (for installing the manpage; if you want
   gzipped manpages, use the target `install.mangz')
 - run `tp4d -d' in a terminal; watch out for error messages
 - run `xtp4' and play around.

 - while (!bored && !works) {
      keep_on_reading;
      re-consult web-page (update ?);
      send me email;
      try_again;
   }

   if (works && you_like_it) {
      put invocation of `tp4d' (without `-d') to a (login/startup) script,
      maybe with your preferred settings (determined by using
      `xtp4') supplied as command-line options.
   } else {
      make uninstall
   }

 - if you intend to run tp4d from a system startup script, you should
   maybe read the respective section below.

INSTALLATION (step by step - some diagnostics):
----------------------------------------------

 -  unzip/untar

 -  run

      xmkmf -a

    Note: maybe you have to massage the (very simple) Imakefile
          so that libXpm and libXaw3d are found.

          Also, there are a few configuration options
          (install locations, switch on/off generation of the
          psctrl device) at the top of the Imakefile.

 -  run

      make

    Note: if xmkmf / make fail, you still can make `tp4d'
          manually. This enables you to verify that your
          trackpoint is working before keeping on trying
          to make `xtp4'.

          If making didn't work, try

             gcc -c version.c 
             gcc -o tp4d tp4d.c version.o -lapm

 -  before installing, you already should verify that
    tp4d is working. Log in as superuser on a virtual console
    and issue

      tp4d -d

    IMPORTANT NOTE: if you have running X, gpm or any other
    program that makes use of the mouse, you _MUST_ run
    tp4d as superuser or chown it to root and turn the suid bit on.

    If there is no X running, you may run tp4d without
    privileges. This enables you to verify successful
    trackpoint detection, but you cannot test the nice features.

    If `tp4d -d' doesn't report an error, you may now switch
    to the X-servers VT and try `xtp4'. 

    (If you dont have got xtp4 successfully `made' yet, you simply
    can try pressing the trackpoint.
    The stick-press --> button1-press feature is enabled by default
    and you should notice something happening.)

 - if the test is successful, you may now test `xtp4':

      make install
      make install.man[gz]

    Note: use the `install.mangz' target if you want the installed
          manpages to be compressed (AFAIK it's safe to do so).

 - there is also a

      make uninstall

   target for removing everything from the install locations.

 - if everything works ok, determine a policy for running `tp4d',
   i.e. call it from the appropriate scripts. If `tp4d' is started
   by a non-privileged user (e.g. on a per-X-session basis), make
   sure to kill `tp4d' when closing the session.
   I'd suggest however to start `tp4d' at system startup as root
   (`rc' script).
   If your session manager changes ownership of the mouse device
   at login, it should also send a HUP signal to the `tp4d' server.
   Every user may then configure his/her preferred settings by
   calling `tp4d -i -S xx -M xx ...` from the login script.

INSTALLATION OF THE psctrl DEVICE
---------------------------------
NOTE: All of the necessary steps to compile, configure and install
      the `psctrl' device are automatically performed by the Makefile
      (unless you did chose to disable these steps by means of
      an `Imakefile' config option).
      The only thing that is _not_ done by make install / make uninstall
      is editing /etc/conf.modules in order for adding/removing an
      appropriate alias definition (see below).
      However, the module should still be found (due to a symlink
      of char-major-10-174.o to psctrl.o) - only the output of
      `lsmod' is perhaps less informative. Dont forget to run
        depmod -a
      after editing /etc/conf.modules!

install the `psctrl.o' module (as superuser) to the appropriate
`misc' module subdir. Normally this is done automatically by the
makefile - in any case, it's better to verify that it was
installed to the correct kernel version's subdir, i.e.

    /lib/modules/2.2.xx/misc/psctrl.o

Add the line

    alias char-major-10-174 psctrl

to the file

    /etc/conf.modules

and, finally, create the device node (normally this is also
done automatically by `make').

    mknod -m 600 /dev/psctrl c 10 174

Note that the char-minor number (174) was
picked arbitrarily - in case of a conflict,
it may be necessary to recompile the module
after changing this number (an Imakefile config option). 
Substitute 174 for the new number in the
`alias' line and the `mknod' command mentioned
above.

tp4d automatically determines whether the psctrl
device is present (and hence can and will be used)
 or not. No compile- or run-time configuration
options are necessary.

RUNNING tp4d FROM A SYSTEM STARTUP SCRIPT
-----------------------------------------

tp4d may well be started at system startup, e.g. by /sbin/init.d/boot.local
However, you should keep in mind the following:

    - some distributions run the X-Server as root and don't give the
      logged-in user read/write access to the mouse (/dev/psaux).

    - tp4d copies the owner-id and the mode bits from the mouse to its
      request/reply pipes. Therefore, a normal user will not be able
      to issue requests.

    - Therefore, e.g. the following lines may be added to the `xdm' config
      files (xdm is also used by KDE/kdm). Note that your particular
      configuration may differ (e.g. does your script set the `USER' variable?)
      and you are strongly advised to carefully study the scripts.

      in /usr/X11R6/lib/X11/xdm/GiveConsole:

            # Turn the mouse over to the user and give her rw access
            chown ${USER}:root /dev/psaux
            chmod 660          /dev/psaux
            # notify the trackpoint daemon that the owner has changed
            killall -HUP tp4d

      in /usr/X11R6/lib/X11/xdm/TakeConsole

            # get the mouse back
            # (probably, we should kill all processes currently connected
            # to tp4d here, but I guess on a laptop we dont have to be too
            # paranoid)
            chown root:root  /dev/psaux
            chmod 660        /dev/psaux
            # notify tp4d
            killall -HUP tp4d

    - if you are not very familiar with xdm configuration, you simply may make
      the mouse world readable/writable. Since we are on a laptop, this is
      probably not a big security problem :-)

        chmod o+rw /dev/psaux

   - If executed from a system startup script, the same tp4d instance keeps on
     running. This means that individual users must remember to restore their
     settings after login (the last users settings are still active). Therefore,
     starting tp4d at boot-time is probably most useful if you are the only
     user...
