Ubit GUI Toolkit 
                               INSTALL & HOWTO File
                           http://www.enst.fr/~elc/ubit
                       (C) Eric Lecolinet - GET/ENST - 2008


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

Mandatory:
  - Linux or MacOSX or Solaris or BSD or Windows with Cygwin
  - X11 *or* GLUT
  - a C++ compiler (typically g++ version 4.*)

Optional:
  - OpenGL (mandatory when using GLUT, highly recommended otherwise[*])
  - FreeType (mandatory when using GLUT, highly recommended otherwise[*])
  - XPM, JPEG, GIF (or UNGIF)

  [*] many Ubit features (such as transparency, 3D widgets...) require OpenGL and/or FreeType

  [NOTE1]: 3D Widgets require a hardware OpenGL implementation. This may be a problem on some
  Linux OS that use a "Mesa" software implementation by default. You must install the appropriate
  graphics drivers to obtain good performance when using 3D widgets.

  [NOTE2]: when using FreeType, obviously, you do not only need the FreeType library but also
  the FreeType fonts. However, for "some reason", some Linux distributions install the FreeType
  library by default, but not the FreeType font directory. Be aware that you will need to install
  these fonts to use the Ubit toolkit properly.

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

  - ubitX-Y-Z.tar.gz: contains the sources files of the library + some exemples and demos 
    (X,Y,Z are the major, minor, micro version numbers)

    this file can be downloaded from: http://www.infres.enst.fr/~elc/ubit

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

  - open a Shell (Terminal/Konsole...) window
  - create the Ubit directory 
    $ gtar zxvf ubitX-Y-Z.tar.gz  (tar on Linux systems)
  - go to this directory
    $ cd ubitX-Y-Z
  - create the configuration files:
    $ ./configure --help      : shows useful options [* see notes below] 
    $ ./configure --with-X11  : creates the Ubit project in X11+GL mode
    $ ./configure --with-glut : creates the Ubit project in GLUT mode
  - compile the library, demos & examples:
    $ make
  - install Ubit on your OS [*]:
    $ make install
    this operation requires appropriate rights and will install Ubit in:
    /usr/local/include and /usr/local/lib (see below)

NOTES:
  - ./configure --prefix=mydir specifies where Ubit will be installed (/usr/local is the default)
  - ./configure --enable-debug compiles Ubit in debug mode
  - the "-fpermissive" g++ option is needed with some obsolete versions of the X11 headers

COMPILING WITHOUT using 'configure': see instructions at the end of this file

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

  in the 'ubitX-Y-Z' directory:
  - src/ubit     : source code of the Ubit library
  - include/ubit : Ubit headers (copied from src/ubit is Ubit is installed)
  - lib          : Ubit library (copied from src/ubit is Ubit is installed)
  - examples     : examples & tutorial
  - demos        : demos (more sophisticated examples)
  - ums          : UMS (Ubit Mouse Server)
  - images       : images for the demos

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

  When launching a Ubit application:
  --help-ubit, --help-x  : prints Ubit options
 
*** UMSD *************************************************************************

  the UMS daemon (umsd program) is created in directory 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 two-handed and multiple user 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)
optionally
  run: ./umsd --help   to get help about the UMSD arguments

*** COMPILING WITHOUT configure *************************************************

  - go to the Ubit base directory
  - edit 'umake/makefile-defs' to change paths and compilation options 
  - edit 'src/ubt/ubit_features.h' to change macros (see example ubit_features.h.default)
  - make -f makefile.umake

*** RELATED PROJECTS ************************************************************

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