Copyright (c) 1995,96,97 by the Institute for Information Processing and
Computer Supported New Media (IICM), Graz University of Technology,
Austria.

May 27, 1997



VRweb 1.5 Unix Source Code
==========================


This source tree contains the complete source code for the Unix/X11
version of VRweb, including the sources of all necessary libraries and
imake configuration files. See file COPYRIGHT for copyright notices!

VRweb uses a modified version of the Stanford/SGI InterViews 3.1 user
interface toolkit and the OpenGL and/or Mesa graphics libraries.

We have compiled and run VRweb 1.5 under SGI Irix, DEC Alpha/OSF1, SUN
Solaris, SUN OS, HPUX, IBM AIX, BSDI, and LINUX. It should not be too
difficult to configure the imake environment for another platform.

Please let us know if you successfully port VRweb to another platform,
so that we can incorporate any fixes/changes you might have into the
master code tree. Thanks to Mike Convey <mike@novell.co.uk> who did so
for Novell UnixWare, to Meredith Whyles <mwhyles@merlyn.galstar.com>
for porting to SCO UNIX, and both to Dave Bodenstab <imdave@synet.net>
and Anton Krasovsky <anton@dawn.ww.net> for a port to FreeBSD, and all
other persons who provided patches and feedback.


Important
*********

To keep up with the library versions used by VRweb which are provided
by Hyper-G/Hyperwave and its Harmony client for Unix/X11, and to make
compilation hopefully a bit simpler, we changed the installation
procedure (again) since the previous release.

The make_world perl script was finally discarded and replaced by calls
of make/imake in the according library subdirectories.

*********************************************************************
** Thus continue to read this installation guide, even if you have **
** already compiled the VRweb source of version 1.3 or earlier.    **
*********************************************************************


                    Have fun,

                               Keith Andrews, Michael Pichler


Keith Andrews       kandrews@iicm.edu     VRweb project leader
Michael Pichler     mpichler@iicm.edu     VRweb lead programmer

vrweb-info@iicm.edu ... General questions
vrweb-bugs@iicm.edu ... bug reports

http://www.iicm.edu/vrweb ... VRweb home page
- see file README for ftp download sites



Contents
--------


- Installation Guide:
        how to build the VRweb software on your system

- Porting to Other Platforms:
        how to compile on a different platform,
        troubleshooting in case of compilation problems

- Graphics Libraries:
        about VRweb's use of OpenGL and the Mesa library

- Spaceball Support:
        how to use a spaceball with VRweb

- The binaries:
        where to continue after successful compilation

- What's where in the Directories?
        source tree structure



Installation Guide
------------------


0. If you can make use of a precompiled version, do so (see README-Unix).
   It will make your life a bit easier :-)

   If you hate reading lengthy documentation upack the source archive
   and enter the following 3 commands in order:

     makeall -r
     makeall -m
     makeall -i

   and see what happens... (it is recommended to read on though).


1. Make sure perl is installed, and a C++ compiler is available.
   We develop using gcc/g++ for fewer portability problems across platforms.
   If you want to use a different compiler, you will have to adjust
   the config files. We recommend using g++ version 2.7.2.


2. gunzip and untar the tar archive. The command:

     gzip -cd vrweb-src-1.5.tar.gz | tar xvf -

   will create a subdirectory vrweb-1.5 (the one also containing this
   INSTALLATION guide). From now on, this directory is referred as $vrweb.


3. The uncompressed source tree takes about 11 MB disk space. During
   compilation this will grow up to about 70 MB (Linux, Solaris) to 85 MB
   (Dec Alpha w/ OpenGL). About one third of this number is put into subdir
   $vrweb/installed, which will be created during compilation to hold
   installed libraries and programs; you can put these data elsewhere by
   creating a symbolic link for installed before starting compilation.

   See below about what's where in each directory.


4. cd $vrweb  and run:  makeall -h

   If you are in the proper directoy it will find the subdir config/scripts,
   where the scripts are located.

   Normally, makeall is able to determine how to set $CPU from the uname
   system call. See below about how it should be set and modify the
   makeall script if necessary.

   You also need to use GNU make instead of the native make command.
   You can either set the path in makeall or create a link,
   e.g.: cd config/scripts ; ln -s /usr/local/bin/gmake make


5. Possible settings of CPU

      [csh/tcsh etc.:]  setenv CPU xxx
   [sh/ksh/bash etc.:]  CPU=xxx ; export CPU

   CPU set to   Machine (using gcc/g++)
   ----------   -----------------------
      SGI_GNU   SGI
     SUN4_GNU   SUN OS
     SUN5_GNU   SUN Solaris
    ALPHA_GNU   DEC Alpha
     PMAX_GNU   DEC Ultix
    HPUX9_GNU   HP
   IBMAIX_GNU   IBM/AIX
    LINUX_ELF   LINUX/ELF
      FREEBSD   FreeBSD

   On other machines you have to modify the configuration
   files in $vrweb/config and $vrweb/config/scripts.
   For some notes on porting, see the next section.


6a makeall -r  will set the RootDir to $vrweb

   ... in config/hg_path.def and config/scripts/hgmkmf.


6b makeall -m  will create Makefiles from Imakefiles

   If you plan to modify source files, you should call makeall -a
   after compilation to create dependencies in Makefile rules.
   For a straight forward compilation makeall -m is sufficient,
   and should take less than a minute.


6c makeall -i  runs the actual make commands

   All machine dependend stuff will be put into $CPU subdirectories,
   allowing compilation on different architectures in one source tree.
   A complete first time build from scratch will take somewhere
   between 15 and 45 minutes (typically 20 to 30).

   You may use "makeall -i -k" to call make -k in all subdirectories.
   Libraries and include files will be installed into $vrweb/installed.
   If this fails somewhere, other program parts needing them will fail
   to compile as well.

   As opposed to the VRweb 1.3 compilation environment, shell output is
   not logged to a file automatically. You may use a command like
   (csh:) makeall -i |& tee make.log


7. When all went well, the stripped binaries (see below about their
   names) are to be found in $vrweb/installed/harmony/bin/$CPU
   and the unstripped binaries are in $vrweb/src/harmony/scene/$CPU.


8. To save disk space you can enter make clean in some of the
   library directories. The larger ones are
   $vrweb/src/harmony/{iicmviews,widgets,mesa}.


9. The procedure described above is only intended for a complete build
   from scratch. If you plan to modify the source code it suffices
   to call make install in the directories affected by the change,
   ensuring proper setting of $CPU and having $vrweb/config/scripts
   in the PATH. Also, dependencies should have been created by calling
   makeall -m or hgmkmf -a (see 6b).


A. Disclaimer: the configuration environment fulfills our internal
   needs (having several library programmers installing their work).
   It is very little adaptive to requirements of users (e.g. adding
   debugging flags or using a different compiler).



Porting to Other Platforms
--------------------------

If you want to build the VRweb source code on another Unix platform
than we did, please note the following:

0. Basic knowledge of perl, shells, Makefiles, Imakefiles, and C++
   will be helpful.

1. Make sure config/scripts/hgimake recognizes your system environment.
   It runs uname -s/-r/-v and sets Defines passed to imake accordingly.

2. Look at config/template to understand how Imakefiles work:

   config/arch.def will determine which configuration file of sort
   hg_XXX.cf to use and sets MacroIncludeFile accordingly.
   Copy a similar hg_XXX.cf and edit it as necessary.
   config/gcc.def contains common gcc definitions.
   HasGcc is used to differ between GNU and native compilers.

   The purpose of imake is to pass template to the macro preprocessor,
   which will include several config files to generate a Makefile:

   Note: the VRweb configuration files no longer depend from X11
   configuration files.

   template includes:

   - arch.def  # sets MacroIncludeFile to the appropriate hg_XXX.def

   - hg_<yourArchitectureName>.def
     . makes machine specific settings
     . includes gcc.def for compilation with gcc/g++

   - hg_path.def
     . directory structure (rootdir set with makeall -r)

   - hg-special.def
     . compilation rules

   - params.def
     . what to build, special flags

   - rules.def
     . compilation rules; no changes should be necessary here

   - Imakefile - consists typically of two parts:
     . a machine independent part: MakeInObjectCodeDir
       that creates a CPU subdirectory and compiles there
     . a machine dependent part (InObjectCodeDir)
       that builds objects, programs, libraries

   - gl.conf
     graphics library and spaceball configuration (see below)

3. Because of different system header files, the Dispatcher library
   (src/common/Dispatch) will probably need some OS-dependent hacks
   to work. Few Imakefiles may be hard-coded for a specific compiler,
   we apologize for that.

4. If you run across problems, and you cannot find an answer
   in this file, look at the VRweb FAQ (FAQ-Unix.html on ftp sites
   or latest version at http://www.iicm.edu/vrweb.FAQ).
   Only if you cannot find an answer there, send a mail to the
   developers.



Graphic Libraries
-----------------


VRweb can use any of three graphics libraries: OpenGL, IrisGL or
Mesa. You can control which of the above versions are made by editing
$vrweb/config/gl.conf:

If OPEN_GL is defined the OpenGL version is made; the same holds for
IRIS_GL and MESA_GL.

Currently gl.conf makes the following "guesses":
On any architecture, make the Mesa version.
On Dec Alpha architectures also the OpenGL version.
On SGI architectures, build all versions.

To use OpenGL, make sure it is installed (include files
/usr/include/GL/gl*.h, libraries libGL[u].a for compilation, and
Xserver with working GLX extension for display). This is always the
case for (almost all) SGI machines; on DEC Alphas OpenGL is part of
the Open3D package and has to be installed explicitly by the system
administrator; Sun's OpenGL is available for Sun Ultra machines with a
Creator 3D board. If you have access to an OpenGL version on your
architecture (e.g. by a 3rd party vendor), just set the #define
OPEN_GL in gl.conf to use it.

The Mesa library (by brianp@ssec.wisc.edu) works on all X displays and
has a programming interface very similar to OpenGL. It is included in
this tar file (release 2.1 with some slight modifications). For more
information look at http://www.ssec.wisc.edu/~brianp/Mesa.html and the
README files in the src/harmony/mesa subdir. Mesa neither needs nor
benefits from 3D graphics hardware accelerators.

IrisGL is available only on Silicon Graphics machines and is now
obsolete, having been superceded by OpenGL. Source to build an IrisGL
binary is still included, but it comprises less functionality than the
OpenGL version.

The included ge3d library is used to encapsulate all graphic library
dependent code from the main application code. The scene/*context
source files implement the link between the graphic library and the
InterViews GUI library.



Spaceball support
-----------------


VRweb supports a Spaceball since release 1.1.2 (and prerelease
1.1s). For more information see the on-line help.

If you have a Spaceball connected to your system, activate the
#define SPACEBALL
in $vrweb/config/gl.conf. You also have to set the appropriate
include path and compiler flags in SpaceballCCFlags and the
library path in SpaceballLDFlags. The settings are the default
paths on SGI systems.



The Binaries
------------


The VRweb viewers are named vrweb-ogl, vrweb-gl, and vrweb-mesa
according to which graphic library they use. The installed (stripped)
versions are to be found in $vrweb/installed/harmony/bin/$CPU, the
unstripped versions (for debugging) in $vrweb/src/harmony/scene/$CPU.

Call the appropriate version of VRweb with the name of a VRML file as
argument, or use argument -h to get a list of possible options. To
install the on-line help pages (installation and usage guide) see the
instructions in file README-Unix.

The Harmony VRweb Scene Viewer (harscened..., to be used only in
conjunction with Harmony, the Hyper-G client for UNIX/X11) is no
longer distributed in source code.



What's where in the Directories?
--------------------------------


. ($vrweb)      ... INSTALLATION, COPYRIGHT, README*, makeall, ...

config          ... configuration files (template, *.cf, *.def)
config/scripts  ... scripts (hgmkmf, hgimake, gccmakedep, ...)

src/common/utils        ... common utilities (data structures) (libHgUtilities)
src/common/Dispatch     ... dispatcher source code (libHgDispatch)
src/common/OS           ... OS part of Dipatcher/InterViews (libHgOS)
src/common/http         ... HTTP tools (libHgHttp)
src/common/hyperg       ... common Hyper-G stuff (libHgHyperg)

src/harmony/iicmviews   ... IICM-Views library source (libIICMViews)
src/harmony/widgets     ... widgets library source (libHgWidgets)
src/harmony/WWWTools    ... WWW tools (libHgWWWTools)

src/harmony/ge3d        ... GE3D: graphics library atop OpenGL/IrisGL/Mesa
src/harmony/mesa/Mesa   ... part of Brian Paul's Mesa library
src/harmony/vrml/qv     ... VRML Qv parser (with some modifications)

src/harmony/scene       ... VRweb core code


installed               ... created during compilation (not part of tar-file)
installed/include       ... installed include files
installed/lib/$CPU      ... installed libraries
installed/harmony/bin/$CPU  installed program files



[end of file INSTALLATION]