   ===================================================================
               Ubit: the Ubiquitous Brick Interactive Toolkit
              a Brick Construction Game Model for Creating GUIs

                Copyright (C) E. Lecolinet - ENST/INFRES 2003

        http://www.enst.fr/~elc/ubit  -  elc@enst.fr (Subject: Ubit) 
 
                               INSTALL file
 
    ===================================================================


*** REQUIREMENTS ***********************************************************

  - Linux/Solaris/BSD/MacOS X with X-Window (X11R5 or X11R6)

  - g++ version 2.95.3 or 3.x

  - The toolkit will be able to display GIF, JPEG and XPM images
    if these libraries are available on your system (this will be 
    automatically detected by configure) 

  - The XML extension of the toolkit (lib ubit_xml) requires the
    Xerces C library (most application won't use this extension)


*** DOWNLOAD ***************************************************************

  - ubitX-Y-Z.tar.gz : sources of the lib + exemples, demos, useful applis

    available from: www.infres.enst.fr/~elc/ubit


*** COMPILATION AND INSTALLATION ******************************************

  - get the current archive file:    ubitX-Y-Z.tar.gz
  - uncompress this file:            gunzip ubitX-Y-Z.tar.gz
  - untar the resulting file:        tar xvf ubitX-Y-Z.tar

  This will create a "ubitX-Y-Z" directory
  - go to this directory:            cd ubitX-Y-Z

  Then execute the following GNU commands:
                                     ./configure
                                     gmake
  * REMARKS:

  - the command:  ./configure --help 
    will give you info about possible configuration options

  - IF YOU DON'T HAVE configure installed on your system
    you can also:
     - edit and customize the ConfMake and src/config.h filed
     - then run:   make -f makefile-xgl


*** DIRECTORIES ***********************************************************

  ubit/src       source of the Ubit lib
  ubit/src/xml   XML extension (uses Xerces C)
  ubit/src/ext   misc extensions (unstable API)

  ubit/examples  simple examples and a small tutorial
  ubit/demos     more sophisticated examples
  ubit/ums       the source of the UMS (Ubit Mouse Server)
  ubit/images    images used by the demos

  Ubit libraries:
  -  libubit
  -  libubit_xml
  -  libubit_ext


*** UMS ******************************************************************

  the UMS demon (umsd program) is created in dir. ubit/ums
  it can manage several mouse pointers on one or several displays.
  it can also handle certain specific input devices such as a MIMIO.
  Ubit programs support bi-manual interaction when an UMS server
  is running on the same machine (optionnaly, they can also open
  connections to remote UMS servers and control remote mouse pointers)

  just start "umsd" with no argument to get help about its arguments


*** NOTES ****************************************************************

  - the lib has been succesfully compiled and tested on Linux, Solaris,
    FreeBSD, MAc OS X, Ipaq Familiar with g++2.95.3 and g++3.x

  - C++ dynamic libs do not work properly on Solaris when using g++2.95.3 

  - some versions of g++ (2.96.?) are buggy and can't be used

  - source code must be compiled with the -fpermissive option on systems
    where the X windows headers have not been updated recently

  - optionally, Ubit can also be compiled with Open or Mesa GL
    (compilation directive: -DGL in the ConfMake file. configure
     can't be used in this case)

  - Among other projects, Ubit was used for making the GUI of VREng
    (Virtual Reality Engine) that is freely available at url:  
    www.infres/enst.fr/~dax


*** COMMAND LINE OPTIONS *************************************************

  - the --help-ubit option prints the list of standard options

  - the --group option should be used when displaying synchoronized
    windows on multiple displays

  - the --no-grab or --sync options are useful for debugging

  --help-ubit, --help-x      : prints this message
  --conf <profile>           : sets configuration profile
  --disp[lay] <displayname>  : uses X-server 'displayname'
  --scale <int>              : sets global scale (0=default, > 0 larger, < 0 smaller)
  --[no-]doubleb[uffering], --[no-]dbf : double buffering mode (slower but avoids flickering)
  --[no-]softw[ins]          : soft window mode
  --[no-]tele[pointers]      : tele pointer mode
  --[no-]group[ware]         : groupware mode
  --[no-]transps[crollbars], --[no-]tsb: transparent scrollbar mode
  --[no-]grab                : disables mouse grabs (for debugging)
  --[no-]sync[hronous]       : synchronous mode (for debugging)

