
Building GNU Maverik on UNIX machines
=====================================

To build Maverik you need X11 and either Mesa (version 3.0 or above),
OpenGL or IrisGL (for older SGI's).

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 UNIX 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.
--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.
--IrisGL - to specify that you want an IrisGL based graphics module.

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

--TDMINCL and --TDMLIBS - to specify the use of the TDM library
                          (i.e. 6 DOF input device support) and where
                          to find its include and library file.
--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 an 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.



Building GNU Maverik on Windows machines
========================================

First, the disclaimer. Windows support should be treated as
experimental. I am unfamiliar with coding on this platform and have
not throughly tested the port. The code works on our machines, your
mileage may vary. Hopefully some Windows guru out there can take a
look at the code to ensure that it is correct :)

Second, what it doesn't do. There is some missing functionality and
odd behaviour with the Windows port:

1) The more obscure events, namely expose, enter/leave and mapping,
are not trapped.

2) Multiple windows do not share contexts. As such text, textures and
display lists may not appear correctly when you have more than one
window.

3) The libraries are statically linked and the kernel assumes that (at
least) all of the standard modules are present. Because of this the
kernel examples cannot be compiled.

4) Only one font is available and, on Windows 98, the spacing of this
can be incorrect.

5) Keyboard events may not be correct for some punctuation characters.

6) The LegibleCity demos fail. It crashes when it attempts to use the
GLU tessellator, although the callbacks specified look fine to me.

7) A fixed visual is used, i.e. the flags which specify the use of a
single buffer, accumulation buffer etc... are ignored.

8) The circular torus intersection routine does not work correctly.

9) No VRML97 or Tiled Rendering support.

Now, how to build the code. There are two options: (1) using Cygwin
and (2) using Microsoft Visual C++. I do not have access to other
compilers, such as Borland, to test the code with.

Using Cygwin
------------

The Cygwin tools are ports of the popular GNU development tools and
utilities for Windows 95, 98, and NT. This provides a UNIX like
environment in which to build Maverik. Cygwin can be downloaded for
free from http://sourceware.cygnus.com/cygwin. 

To build Maverik using Cygwin start a shell and untar the Maverik
distribution file which creates the directory structure shown at the
end of this document. 

Move into the Maverik directory and untar the cygwin.tar.gz files
located in the top level and demo directories (the later will only be
present if the optional Maverik demos distribution was
downloaded). These overwrite the standard UNIX makefiles and scripts
with Cygwin compatible equivalents, although the differences are
minor.

Then, type "./setup --OPENGLINCL=<include command>" where <include
command> is the command needed to include the OpenGL header file,
e.g. -I/someplace/incl. Then type "make" to compile the Maverik
library, example programs, and any demo programs present.

Using Visual C++
----------------

Yet another warning. I've never used this compiler before and the
instructions I am about to give are certainly not the best way to
use it. However, they are sufficient to get a Maverik application
running. Actually, the instructions are from memory and so may be
incorrect and/or incomplete. Maybe somebody could write a project 
file :) 

Create a new directory and copy into it all the files in the incl and
src directories, and *one* source file from the examples directory
(for example, eg1.c in examples/MPG). Create a new empty console
application project. Add to the project all the files in the new
directory. Add "glu32.lib" and "opengl32.lib" to the list of libraries
linked against. Add the new directory to the include path list. Switch
off the use of pre-compiled headers. Define the variable
MAV_OPENGL. Build and run the executable.



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-5.1/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-5.1

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-5.1
    |
    +-- 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   
