This file contains instructions for compiling the xgobi
executable.  If you wish to use XGobi in conjunction with S,
you will also want to follow the instructions below for the
installation of the S function.

This release is dated March, 1998.

If you want to get a newer distribution before starting,
try this url, and see if the distribution there is newer:

   http://research.att.com/~andreas/xgobi/xgobi.html

We used to keep the latest distribution on statlib, but
we're falling behind there:

   http://lib.stat.cmu.edu/general/XGobi/

   ftp lib.stat.cmu.edu, log in as statlib
   cd general/XGobi
   mget *


1) Compile xgobi

Using the Imakefile:

  I strongly recommend trying this method first. 

  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)
   * to reset the random number generator in casse drand48()
     isn't present on your machine

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

/**/#  Choose a random number generator, random or drand48
              #R = USE_RANDOM
               R = USE_DRAND48

  Copy the Imakefile into the src directory, and execute 'xmkmf'
  (x make makefile) to generate the Makefile.  It should be as
  easy as that.

Hand-crafting the Makefile:

If that doesn't work, you'll need to build your own Makefile by
hand.

a)  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.

b) 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

c) 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
  XGOBIDIR points to that directory.

  You may also want to change the setting for the random number
  generator to be used.  Some machines have both drand48 and
  random, but some have only one or the other.


d) Make xgobi

  Just type 'make' and a new version of XGobi will be compiled.

2) Install the S function

a)  Edit the file Sfunction

  The file Sfunction contains the definition of the XGobi S
  function, named xgobi().  Find the line in which the pathname of
  the XGobi executable is specified, and edit it to point to your copy.

b)  Source Sfunction

  Initiate a New S session, and then type source("Sfunction") to
  define the XGobi S function.  (XGobi works with New S, whether
  your version came from AT&T or from StatSci.)

c)  Install the help page

  The file doc/Sfunction.d contains the S help page.  Move it to
  .Data/.Help/xgobi.

NOTES
  
a)  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.

b)  Interaction with S

  When XGobi is initiated from within S, the S data of interest is
  written out to an ascii file, which XGobi then reads in.  When XGobi
  wants to write out coefficients or brushing ids to S, it directly
  writes .Data/filename in the S data format.  We are exploring a
  connection to S that uses UNIX inter-process communication methods.

c)  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.

d)  Documentation

  Read Readme.doc for information about XGobi documentation.

e) 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.

f) Compiling under Solaris

  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 just told me that, in order to run xgobi under Solaris,
  he had to set LD_LIBRARY_PATH to /opt/SUNWspro/lib:/usr/openwin/lib.
  I haven't had that problem.

  Since then, I've been reprimanded for suggesting the use of
  LD_LIBRARY_PATH at all.

g) 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.

h) 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

  If you can find the file, you can edit xgobitop.h to supply
  a full pathname.