                      Geomview/OOGL Release 1.6.1
                         The Geometry Center
			  November 15, 1996
			  -----------------

CONTENTS
========

        Introduction
        Setup
	  Configuring graphics type
	  Configuring XForms
	  Configuring Tcl/Tk
        Unknown Architectures
        Summary
        Compiling and Installing
        Machine Specific Notes
          - SGI
          - NeXT
          - Dec Alpha
          - Linux
          - HP-UX


INTRODUCTION
============

NOTE: This file was obtained by adapting the "Installation"
  chapter of the Geomview manual to this unified source release.
  For references to things not in this file, see the manual, but
  be aware that the manual was written for the SGI and NeXTStep
  version and may not be correct for the X11 version.  If you
  have trouble compiling or installing this distribution on your
  system, send email to software@geom.umn.edu and we'll try to
  help you out.

  The manual is distributed in the "doc" subdirectory.

The main reason to get the source code distribution is to look at
and/or work with the source code.  If you are only concerned with
*using* Geomview it is better to get the binary distribution.  It
takes anywhere from 15 minutes to 1.5 hours to compile the entire
source distribution, depending on what kind of computer you have.


SETUP
=====

Let `$GEOMROOT' denote the full pathname of the Geomview source
code directory; this is the directory called `Geomview' that is
created when you unpack the distribution.  This directory
contains the Geomview source code as well as various other files
and subdirectories that Geomview needs when it runs.

Before doing any compilation you should edit the file
`$GEOMROOT/makefiles/mk.site.default'.  This file defines some
`make' variables which specify your local configuration.  This
includes the pathnames of the directories into which Geomview
will be installed, and possibly some other settings as well.
There are comments in the file telling you what to do.  This file
is included by every Makefile in the source tree, so the settings
you specify here are used throughout the source.

Briefly, before compiling, you'll want to edit the following files:

$GEOMROOT/makefiles/mk.site.default
		to specify the absolute pathname for GEOMROOT
		and installation directories (BINDIR, MANDIR, ...)
		for binaries, documentation, external modules, etc.

$GEOMROOT/makefiles/Makedefs.global
		to hard-wire the CPU type, if you don't use the CPU
		    environment variable when compiling;
		to set system-independent compiler options (COPTS),
		    e.g. COPTS = -O rather than COPTS = -g;

$GEOMROOT/makefiles/mk.<CPU>
		to set architecture-specific compiler options,
		(CC and SYSCOPTS),
		linker flags for locating system libraries
		(SYSLIBS for general libraries, SYSXLIBS for X,
		SYSMOTIFLIBS for Motif),
		graphics type (MGTYPE and MGLIBS),
		FORMS library setup (FORMSLIBS and FORMSINC),
		Tcl/Tk library setup (TKLIBDIR and TKINCDIR).

You can compile for several machine types in the same directory tree.
The Makefiles are set up to put the object files,
libraries, and executables in directories which depend on the
type of computer, so the different architectures will not
interfere with each other.  The Makefiles use a variable called
`CPU' to determine the type of machine. Before doing any
compilation you must arrange for this variable to have a value.
There are two ways you can do this.

  1. If you will always be compiling Geomview on the same type of
     computer, edit the file `$GEOMROOT/makefiles/Makedefs.global'
     to set the `CPU' variable to one from the table below (read
     on if your machine isn't in the table).  The comments near
     the top of that file will tell you where to do this.

  2. If you will be compiling on different types of computers you
     can set a shell environment variable named `CPU' to one from
     the table (keep reading if your machine isn't in this list),
     and the Makefiles will inherit the value from the
     environment.  You will need to do this in every shell in
     which you plan to do compilation.

     Alternately, you could modify your shell initialization file
     (`.cshrc' or whatever) to set `CPU' appropriately.

    Machine		    CPU variable    Directory name   Default compiler
    -------		    ------------    --------------   ----------------
    SGI			    iris4	    sgi		     cc
    NeXT		    next	    next	     cc
    Sun Sparc, SunOS 4.1.x  sun4	    sun4	     gcc
    Sun Sparc, Solaris 2.x  solaris    	    solaris	     gcc
    Linux		    linux	    linux	     gcc
    FreeBSD		    FreeBSD	    x11		     gcc
    HP Risc		    hpux	    x11		     cc
    HP Risc		    hpux-gcc	    x11		     gcc
    Dec Alpha		    alpha	    x11		     cc
    RS/6000		    rs6000	    x11              cc


Configuring graphics type
=========================
Choose the graphics type Geomview should use by setting `MGTYPE'
in `$GEOMROOT/makefiles/mk.XXXX' to one of `-DMGX11', `-DMGGL',
or `-DMGOPENGL'.  Also set MGLIBS to the list of system-supplied libraries
needed to use that type of graphics, e.g. `-L/opt/OpenGL -lGL -lGLU' for
Open GL.  See the existing makefiles/mk.<CPU> files for examples.

Configuring XForms
============
Many modules for previous versions of geomview depended on the GL-based FORMS
library.  FORMS has now been adapted for pure X by its original author,
Mark Overmars, and T.C.Zhao; binary-only libraries are available from

   ftp://laue.phys.uwm.edu/pub/XForms

If you retrieve that package, you should extract from it libforms.a and forms.h,
install them somewhere, and add settings for FORMSLIBS and FORMSINC to
the appropriate mk.<CPU> file.  FORMSLIBS should list the Forms library
and any other libraries it requires, e.g.
  FORMSLIBS = -L/usr/local/lib -lforms -lX11
or if you want to try the old GL-based FORMS after all,
  FORMSLIBS = -lforms -lgl_s -lfm_s
FORMSINC should have any -I compiler flags needed to find the forms.h
include-file.

If you don't have a FORMS library installed, be sure to comment out any setting
of FORMSLIBS in the mk.CPU file, to avoid trying to compile those programs.

Note that, at present, you can't compile geomview with the XForms library
to get something resembling the old interface; and some of the old FORMS-based
modules don't work either, though many do.

The FORMS modules here still have interfaces created with the old GL-based
FORMS designer; the new XForms designer produces .c/.h files incompatible
with the old one (there's no longer a global variable per FORMS object,
and coordinates are Y-flipped in X style).  If you need to use the XForms
designer to change a panel, you'll need to finish porting that module to 
XForms.


Configuring Tcl/Tk
==================
A number of new modules use Tcl/Tk, including the N-D utilities written by
Brian Luense, and new non-FORMS versions of Crayola and the N-D viewer.
To compile them, you must install Tcl/Tk (with tk version 4.0 or later),
which if you don't have it already is available from
   ftp://ftp.smli.com/pub/tcl
Then in the mk.CPU file, set TKLIBDIR to the directory containing
-ltcl and -ltk object libraries, and TKINCDIR to the directory where
tcl.h and tk.h reside.  If your libraries aren't named -ltcl and -ltk,
see makefiles/Makerules.TKmoduleobj.

If you don't have Tcl/Tk, be sure to comment out any TKLIBDIR and TKINCDIR
setting in your mk.CPU file, to avoid trying to compile those programs.


UNKNOWN ARCHITECTURES
=====================

If you are using a machine not listed here, you must create a
file in the `$GEOMROOT/makefiles' directory named `mk.XXXX',
where `XXXX' is a string representing your machine type (the
setting of `CPU').  One way you can do this is by making a copy of
`$GEOMROOT/makefiles/mk.sun4' and modifying it to suit your
machine.  You'll need to choose a setting for `MACHTYPE', which
could be "x11", "sun4" or "linux".  Once you have created
`$GEOMROOT/makefiles/mk.XXXX', edit
`$GEOMROOT/makefiles/Makedefs.global' and set the `CPU' variable
to `XXXX'.

If you need any architecture-specific compiler options, such as
include directives for the X or Motif libraries
(e.g. `-I/usr/local/X11R5'), add them to the setting of `SYSCOPTS' in
`$GEOMROOT/makefiles/mk.<CPU>'.  Likewise, add settings for
system-specific libraries to `SYSLIBS', and for X or Motif
libraries to `SYSXLIBS', in the `mk.<CPU>' file.





COMPILING AND INSTALLING
========================

Once you have configured your source tree by editing the files as
described above and setting the `CPU' variable, you can compile
and install Geomview by typing `make install' in the `$GEOMROOT'
directory.  You can also type `make all', or equivalently just
`make', to compile without installing, and then type `make
install' later to install.

You can use these same `make' comands in any subdirectory in the
tree to recompile and/or install a part of Geomview or a module.

If you want to modify the complier flags used during compilation, edit
the file `$GEOMROOT/makefiles/Makedefs.global'; the `COPTS'
variable specifies the flags passed to the C compiler (cc).


MACHINE SPECIFIC NOTES
======================

SGI
---

The SGI version of Geomview can be compiled with two different
styles of user interface: the Forms library, and the Motif
interface which is also used for the X version.  You will want to
compile with the Motif user interface if you want to run Geomview
over the network -- the Forms library won't work right.  The user
interface to be used is selected by changing the value of
`GVTYPE' in mk.iris4 (there are comments showing where to change it).

When compiling the SGI version of Geomview, you can also select
which type of graphics to use.  Normally you want to use GL
graphics, which will take advantage of SGI's graphics hardware.
You can also select the X rendering engine.  This would be needed
if you want to display Geomview remotely to a non-SGI machine.
The graphics type to use is selected by changing the value of
`MGTYPE' in mk.iris4 (there are comments showing where to change it).

NeXT
----

If you want to compile fat binaries under NeXTStep 3.1 or later,
before doing any compilation edit the file
`$GEOMROOT/makefiles/mk.next' to uncomment a particular line
there.  There are comments in the file telling you which line to
uncomment.

Dec Alpha
---------

When compiling for a Dec Alpha (assuming you're using DEC's
'make'), you will need to make one change in addition to setting
CPU equal to 'alpha'.

In ${GEOMROOT}/makefiles/Makedefs.global you will need to replace:

MKFILEDIR = ${GEOM}/makefiles

with

MKFILEDIR = .

The reason for this is that on most machines, 'make' seeks
included files relative to the current working directory where
'make' is running. However, on the Dec Alpha and perhaps other
machines, 'make' looks for included files relative to the
directory containing the including Makefile.

Linux
-----

Geomview needs access to some C++ iostream routines from the GNU library.
The name of the library containing these has changed a few times
for different gcc/libg++ versions; see the comments in
${GEOMROOT}/makefiles/mk.linux to tell whether you'll need to adjust
them for your site.
