
Building GNU Maverik
====================

To build Maverik you need OpenGL (and/or IrisGL on SGI's) or Mesa
(version 3.0 or above) and X libraries.

Untar the Maverik distribution file which creates the directory
structure shown at the end of this document.

Move into the Maverik directory and type "./setup" followed by
"make". This will compile the Maverik library, example programs, and
any demo programs present.

The "setup" script generates a Makefile appropriate to your
machine. Currently supported platforms are Irix, GNU/Linux and
SunOS5. However, we believe that Maverik itself should compile on any
UNIX platform with X11 and OpenGL/Mesa, so, if you are using a
different platform, edit the script, fill in the appropriate values
and mail us the amendments for inclusion in the next release.

The setup script accepts the following command line arguments:

--help - prints a help message detailing these arguments.
--debug - to compile with "-g" rather than full optimization.
--Voodoo - to specify that you have a Voodoo graphics based 3Dfx board.
--VRML97 - to specify that you want VRML97 support (requires a C++
           compiler, flex and bison).
--MESAPATH - to specify where Mesa is installed if it is not somewhere
             where the compiler will automatically pick up. Also see
             note below.
--XLIBPATH - to specify where the X library is installed if not in
             /usr/X11R6/lib.

The setup script is also used to specify the use and location of
optional libraries, specifically:

--TIFF - to specify the use of TIFF. This option assumes that the
         include and library files are located where the compiler will
         automatically pick them up. If this is not the case, use the
         next 2 options instead of this this one.
--TIFFINCL and --TIFFLIBS - to specify the use of TIFF and where to
                            find its include and library file.
--TDMINCL and --TDMLIBS - as above but for the TDM library (i.e. 6 DOF 
                          input device support).
--TRINCL and --TRLIBS - as above but for the Tiled Rendering library.

Maverik does not require these libraries and if you dont know what
they refer to, forget about them, they're not for you.

An Irix6.x complication use the n32 ABI and, if R10k processor is
detected, mips4 and -r10000 options. 

"-O2" optimization is used on Irix platforms, and "-O2
-finline-functions -fomit-frame-pointer -funroll-loops -ffast-math" on
GNU/Linux.

If the Mesa library file is not installed somewhere where the compiler
will automatically pick it up, GNU/Linux users may need to add its
location to their LD_LIBRARY_PATH in order to link and run the Maverik
examples. This is not the case for an RPM installation of Mesa.



Testing the system
==================

To test that the Maverik libraries and examples have been successfully
compiled, we suggest you try executing eg1 in the examples/MPG
sub-directory of the Maverik distribution. You should see a window
appear and display the Maverik welcome message (which consists of
a spiraling Maverik logo with various copyright, version and contact
information). When the message clears you should see an empty blue
window. Press Shift-ESC to quit.

Note that the Maverik libraries are dynamically linked so you may need
to set your LD_LIBRARY_PATH (or LD_LIBRARYN32_PATH for Irix6) to
include the Maverik library directory in order to run the example
program, e.g. for a bash shell:

export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/Maverik-4.3/lib

GNU/Linux users may also need to add the location of the Mesa library to
this line, see note in previous section.



Compiling with Maverik
======================

The Makefiles for the example programs have been made as simple as
possible so as to allow them to be used for compiling your own Maverik
programs (or indeed versions of the examples that have been copied
into a users workspace and modified). To use these Makefiles you
will need to set the following environment variables:

1) MAV_HOME to indicate where Maverik is installed
   e.g. export MAV_HOME=/usr/local/Maverik-4.3

2) CC to specify the various compiler options
   e.g. for GNU/Linux
   export CC="gcc -O2 -finline-functions -fomit-frame-pointer -funroll-loops"

   e.g. for Irix6 with an R10k processor
   export CC="cc -n32 -mips4 -r10000 -O3"

Both of these environment variables are correctly set for you when the
example are automatically compiled.



Contents
========

The Maverik distribution contains the source code, include files,
worked example programs and documentation consisting of a Programmers
Guide (to accompany the examples) and a Functional Spec. Also
available via a separate download is a Maverik "demos" distribution
which contains a number of applications that have been developed using
Maverik.

The tar file creates the following directory structure:


 Maverik-4.3
    |
    +-- demos (essentially empty, available as a separate download)
    |
    +-- doc
    |    | 
    |    +-- MPG (Maverik Programmers Guide)
    |    |    |
    |    |    + sub-directory for postscript version
    |    |
    |    +-- MFS (Maverik Functional Specification)
    |         |
    |         + sub-directories for postscript, HTML and man page versions
    |
    +-- examples
    |    |
    |    +-- MPG
    |    |
    |    +-- kernel
    |    |
    |    +-- misc
    |         |
    |         + various sub-directories
    |
    +-- incl
    |
    +-- lib
    |    
    +-- src 
         |
         +-- SMS
         | 
         +-- callbacks
         |
         +-- extras
         |    |
         |    + various sub-directories
         | 
         +-- gfx
         | 
         +-- kernel
         | 
         +-- navigation
         | 
         +-- objects
         | 
         +-- windows   
