This file contains instructions for compiling the `xgobi' and `xgvis'
executables.

// Heads up:  A descendant of xgobi, to be named ggobi, is
// now in the works.  It's built using gtk+ (www.gtk.org)
// so it looks quite different and it'll be more portable
// than xgobi.  It has an API, and can be embedded in R,
// resulting in a powerful combination of direction manipulation
// graphics and a statistical programming language.
// You can find it on www.ggobi.org.

This release is dated September, 2001.  If you want to get a newer
distribution before starting, try this URL, and see if the
distribution there is newer:

//////////////////////////////////////////////////////////////
//  http://www.research.att.com/areas/stat/xgobi/
//////////////////////////////////////////////////////////////

* Documentation: two papers that are the closest thing to manuals
  - for XGobi: 
     http://www.research.att.com/areas/stat/xgobi/index.html#xgobi
  - for XGvis:
     http://www.research.att.com/areas/stat/xgobi/index.html#xgvis

* Statlib: We used to keep the latest distribution on statlib
  (http://www.stat.cmu.edu/general/XGobi/), but it's quite old at the
  moment and will be removed.

* S users: If you wish to use XGobi in conjunction with S, read
  Readme.S.

* RPC: If you wish to use XGobi in conjunction with RPC, study the
  Imakefile or the Makefile it generates; if necessary ask
  symanzik@galaxy.gmu.edu.


//////////////////////////////////////////////////////////////
//  Install xgobi and xgvis
//////////////////////////////////////////////////////////////

In the best case, all you need to do is the following:

  Unpack the shar file `xgobi.sh' which creates a subdirectory
  `xgobi', go to `xgobi/src', create `Makefile' automatically from
  `Imakefile' by executing `xmkmf', compile by executing `make', and
  finally run by typing `xgobi filename' or `xgvis filename'.

  For example:

////////////////////////////////////////////////////////////////
//     /bin/sh xgobi.sh     # unpack the shar file
//     cd xgobi             # go to the newly created subdirectory
//     cd src               # go to the source files
//     xmkmf                # create `Makefile' from `Imakefile'
//     make                 # compile xgobi and xgvis
// 
//     # make the xgobi and xgvis executables available,
//     # eg, by adding this directory to your path:
//     set path = ($path `pwd`) # csh, tcsh, ... users
//     export PATH=$PATH:`pwd`  # ksh, bash, ... users
//     # The above will work for this session; for later
//     # sessions, add the appropriate line to your startup
//     # file, replacing "`pwd`" with the full pathname of the
//     # `src' directory
//
//     # finally run two examples: 
//     # the places rated data and the morsecode data
//     xgobi ../data_xgobi/places
//     xgvis ../data_xgvis/morsecodes
////////////////////////////////////////////////////////////////

  If something doesn't work, read on.  

  * Most likely something went wrong in `make', in which case you may
    have to edit `Imakefile' and recreate `Makefile'.

  * If `xmkmf' just doesn't work, copy a `Makefile*' from the
    directory `makefiles' and tailor it; see below.


////////////////////////////////////////////////////////////////
// Editing the Imakefile

  These are the lines in the Imakefile you might want to edit:

  * to prepare to install xgobi somewhere other than where
    you're compiling it,
  * to specify a C compiler
  * to turning debugging off (to generate smaller binaries)

////////////////////////////////////////////////////////////////
//          XGOBID = $(PWD)/..
//              CC = cc
//              LD =
//     CDEBUGFLAGS = -g
////////////////////////////////////////////////////////////////

  If you know how `xmkmf' works, you can further edit the Imakefile to
  make it work, but we don't know enough about it to tell you how.



////////////////////////////////////////////////////////////////
// Editing or hand-crafting the Makefile

//  Editing the Makefile

  Using Sun's CDE

  One xgobi user says that he simply replaced /usr/openwin/bin and
  /usr/openwin/lib with /usr/dt/bin /usr/dt/lib in the Makefile
  that was generated by 'xmkmf.'  After that, his compile was
  successful.

// Hand-crafting a Makefile

  If you can't figure out how to edit the xmkmf-generated Makefile,
  you can work with the example in the directory 'makefiles'

Find the X libraries and include files:

  First determine where the X libraries and include files live on your
  system.  The top-level X11 directory might be called /usr/X11 or
  /usr/local/X11, with subdirectories include and lib; alternatively, the X
  libraries and include files may be merged with other system files in
  /usr/include and /usr/lib.

Edit the Makefile to point to X:

  Edit the XGobi Makefile, changing the following two lines to point to the
  X11 include files and libraries on your machines:

  IDIR= -I/usr/local/pkg/X11/include
  LDIR= -L/usr/local/pkg/X11/lib

Other editing that might be required:

  In order to use the XGobi help and print facilities, you need to
  choose a parent directory in which the help and ps subdirectories
  can be found and then edit the Makefile so that the variable
  XGOBID points to that directory.

////////////////////////////////////////////////////////////////
// Notes
//

// Resources

  !! WARNING !! :

  If you had an older version of XGobi on your system, then you
  should make sure that there is no system XGobi resource file
  -- it's no longer needed, and it will now interfere with the
  layout.  It might be in a system directory named app-defaults
  under X's home directory, in a subdirectory named lib or
  Xlib.  Or it might be that you've put it somewhere else and
  set up shell variables to point to it:  check the values of
  $XFILESEARCHPATH, $XUSERFILESEARCHPATH, and $XAPPLRESDIR.

  We've included a file named XGobi.ex as an example of the
  resources you'd be most likely to want to tailor in your own
  resource file (which you would name XGobi).  You (Here you are a
  user, not a system administrator.) may want to adjust some
  colors, for example, or change the size of the variable labels,
  or use a different font.  If you do, then choose a place to put
  that file -- one custom is to use the directory
  $HOME/app-defaults -- and then define XUSERFILESEARCHPATH to be
  $HOME/app-defaults/%N.

  !! WARNING !! :

  A couple of people have had a strange problem with resources,
  where just by creating a resource file and putting one or two
  lines in it, they've ended up with an XGobi window with its
  resources completely haywire.  The solution seems to be to
  make certain that XFILESEARCHPATH does not include any
  reference the the private resource files.  Only
  XUSERFILESEARCHPATH can be safely used for that purpose.


// Space requirements

  Nearly all arrays in XGobi are dynamically allocated, so the only
  limitations you should encounter will be the result of space
  limitations on your machine.  XGobi processes I have observed are
  between 1Mb and 2Mb in size -- X programs run large.

  There are a few arrays whose length is NCOLS: if you plan to read in
  a matrix with more than 200 columns, change the definition of NCOLS
  in xgobitypes.h and recompile.


// Sun bug

  Thanks to Brian Fitzgerald for the following comment:

  Due to a bug in Sun's ld and/or libXmu.s[ao].4.0, some people
  get this error message:

  ld: Undefined symbol
     _get_wmShellWidgetClass
     _get_applicationShellWidgetClass
  *** Error code 2

  This is described in comp.windows.x FAQ 94.  Sun patches 100170,
  100512, and 100573 fix these bugs.  

  Linking with ... -Bstatic -lXmu -Bdynamic ... is a known
  workaround.


// Compiling under Solaris

  Some folks have told me that setting OPENWINHOME in the
  Makefile (or even the Imakefile?) solves a lot of problems,
  including the mysterious menu12 bug (see below).

  If you want to compile xgobi under Solaris, and you can't get
  the Imakefile's Makefile to work, change the LIBS line in the
  Makefile to

  LIBS= -L$(LDIR) -R$(LDIR) -lXaw -lXt -lXmu -lXext -lX11 -lsocket -lnsl -lm

  Somebody told me that, in order to run xgobi under Solaris,
  he had to set LD_LIBRARY_PATH to /opt/SUNWspro/lib:/usr/openwin/lib.
  Somebody else said that using the -R option above eliminates the
  need to tinker with LD_LIBRARY_PATH.


// Optimization in compiling

  We've experimented a bit with optimization; it's certainly
  possible to optimize the compilation of XGobi, using either
  cc or gcc, but we've never seen it make a difference in
  execution speed because usually it's the graphics operations
  that limit XGobi's speed.


// Missing menu12

  We don't know why some X Window System installations don't have
  the 'menu12' bitmap readily available when most do.  For us, the
  file menu12 is installed as

  /usr/include/X11/bitmaps/menu12

  We include a copy of the file in the bitmaps directory in
  case you can't find it.