                              The FOX GUI Library Installation
                              ================================
 
                                

Systems Which are Supported or Known to work:
=============================================

  o LINUX 
  o Windows 2000, Windows NT 4, Windows 9x, (VC++, Cygwin1.1 or Mingw32,
    Borland C++)
  o Digital Unix/COMPAQ Tru64  OSF1 3.2, 4.0x
  o SGI IRIX 5.3, 6.1, 6.2, 6.4, 6.5 (MIPS Pro C++)
  o SUN Solaris, SunOS (gcc, SUN WorkShop Compiler)
  o HP-UX 9.x and 10.x
  o AIX 4.2
  o FreeBSD
  o Sequent DYNIX/ptx 4.4.7
  o IBM VisualAge C++ 3.5 (Windows)



For most UNIX systems.
======================

For most unix systems which have OpenGL installed, you can type:


  ./configure


You can disable OpenGL support with --with-opengl=no.  You can also force MESA 
if your system has both; this is useful if e.g. OpenGL is broken.  To force 
MESA, use --with-opengl=mesa.

After configure runs its course, simply type ``make'' to build the library,
and ``make install'' to install it.

FOX should compile on most unix platforms; we have tested the following:
SGI, IBM, HP, SUN, DEC, LINUX, all with gcc; however, FOX uses a fairly 
conservative subset of C++, and should be no problem to port to other, more 
primitive, C++ compilers.

When programming against FOX, you should only have to include "fx.h", and
for 3D programs, "fx3d.h".  To use keyboard symbols, include "fxkeys.h" also.
Specifically, to remain portable application programs should NOT include any X
window header files.

You may of course need other system headers ("stdio.h", "gl.h", etc).



Building Shared or Non-Shared Libraries.
========================================

You can build FOX either as shared library, static library, or both.  The
default is both.  To build static library only [this may be necessary on
certain systems where shared library support is lacking]:


  ./configure --disable-shared
  

to build shared library only:


  ./configure  --disable-static
  
  

Building for Debug or Release.
==============================

FOX can be built with three levels of debugging.  Full debug executables are 
build by configuring with:


  ./configure --enable-debug
  
  
Building for debug will add debug symbols as needed by your debugger.  It also
includes assert and tracing into the library.  This setting is recommended if
you need to debug the FOX library itself.


Normal builds [w/o any special arguments to configure] will include assert and
trace statements into the library, but no debug symbols.  This mode compiles
the fastest and allows for tracing of the FOX library.  This mode is the
recommended way to develop FOX applications, as it allows for resource tracing
and internal consistency checks.


To build for release, use:


  ./configure --enable-release
  
  
Release builds strip all debug information, asserts, and tracing, and generates
optimized code.  The resulting library is the smallest/fastest, and this is the
recommended setting for production code.



For LINUX systems.
==================

You will need to install the Mesa graphics library.  FOX is being developed
on RedHat 6.1 and Mesa 3.0.  It is known to work with older versions of RedHat
or Mesa.  I recommend Mesa 2.6 or above.

With regard to 3D, FOX may be build three ways:


No 3D support whatsoever:

  ./configure --with-opengl=no
  

Linking against Mesa:  

  ./configure --with-opengl=mesa
  
  
Linking against Native OpenGL:

  ./configure --with-opengl=opengl


Under normal circumstances, configuration will find OpenGL if it is available
on the machine, and will build the libraries to use it.


On SGI IRIX 6.x
===============


On SGI Systems where MIPS Pro C++ compiler is used instead of GCC, you will
need to set the environment variable CXX to:


  CC -n32

before running configure with:


  ./configure --with-opengl=opengl --x-libraries=/usr/lib32


The first argument is only needed if you also have MESA on your system.
FOX searches for the png library [for Portable Network Graphics, the successor
of GIF],  but the library it finds, even though it has the same name, is not
the right one.  You will need to disable this feature, or download the PNG
library from http://www.graphicswiz.com/png/ and compile it, and pass the 
appropriate flags for your compiler to find the new version.
If compiling without PNG, pass the flag:  --disable-png; likewise, you
can disable JPEG with the flag: --disable-jpeg.




Compiling FOX with the SUN WorkShop Compiler
================================================

To use the SUN compilers, simply configure FOX as follows:

  > cd fox
  > env CC=cc CXX=CC LD=CC ./configure


Explanation:

The SUN compilers require 'CC' to be used instead of 'ld' for creating the
shared object library. This is to ensure that template instances will be 
included in the library. To build a static library 'CC -xar' should be 
used instead of 'ar' but there is no simple way to do this, due to 
limitations in 'libtool'.

To get around this problem, the configure script invokes 'CC' with the
argument '-instances=global', thus including template instances in the
object file instead of using a template repository. This works fine and
'ar' can be used to build a static object library.

Daniel Gehriger <gehriger@epfl.ch>



Windows 95/98/NT Builds
=======================

We currently build FOX on a regular basis using Microsoft Visual C++ 6.0.
There is also support for Mingw32, the latest net release of Cygwin (v1.1)
and Borland C++. We have heard of mixed success with building under Symantec's
C++ 7.5 compiler.

A few things to keep in mind:

 1. If you want to include OpenGL support be sure to define the HAVE_OPENGL
    symbol on the compiler's command line, and to link your executables to
    the opengl32.lib and glu32.lib libraries.

 2. The native Windows version of FOX relies on an undocumented API called
    _TrackMouseEvent() which is found in comctl32.dll. You should be sure
    to link your FOX applications with the comctl32.lib import library.
    Note that for this function is only available for comctl32.dll
    versions 4.70 or later; the latest version of this DLL can be downloaded
    from Microsoft's web site:

	http://www.microsoft.com/msdownload/ieplatform/ie/comctrlx86.asp

    If you are running Windows 98, Windows NT 4.0 SP3, or have installed
    Internet Explorer 4.0 or later, you *probably* already have the latest
    version of this DLL already.

 3. The FOX registry mechanism uses the regular Windows registry under the
    hood; those functions are found in advapi32.lib which is not always a
    standard library. If you get some unresolved symbols at link time (esp.
    with names beginning with "Reg") try adding advapi32.lib to the list
    of libraries.


Building with Microsoft Visual C++
==================================

We now have a project workspace and project files set up for Win32 builds
under Visual C++ 6.0. To use these, perform the following steps:

  1. Download the latest fox.tar.gz from the web site;

  2. Unzip & untar in your favorite place;

  3. Start Visual C++ and open the fox/windows/vcpp/win32.dsw workspace;

  4. Choose a project and build it. The project corresponding to the library
     itself is named "fox", and all of the other projects list it as a
     dependency. So if you choose, say, "glviewer" to build, it should first
     build the library and then build the glviewer test program.


Building with Borland C++ Compilers
===================================

The Borland makefiles are now tested semi-regularly against the free
command-line compiler tools (compiler version 5.5) distributed by
Borland/Inprise. We believe that they should also be usable for any recent
Borland C++ compilers (e.g. Borland C++ Builder 3 or later).

To build the FOX library, utility programs and example programs, change to the
fox-0.99.xxx\windows\borland subdirectory and type "make". It should compile
without a hitch, with the possible exception of building the OpenGL test
programs in the "tests" subdirectory:

 + If you're using the free command-line compiler tools, you want to be sure
   that the %BCCDIR%\Lib\PSDK directory appears in the linker configuration
   file (%BCCDIR%\Bin\ilink32.cfg). If it isn't there, the linker won't know
   where to find the opengl32.lib and glu32.lib import libraries.

 + If you're using an older Borland compiler, you similarly want to be sure
   to have the updated OpenGL SDK for Win32 (including the OpenGL 1.2 header
   files and import libraries).

If for some reason you don't have the correct header files and import libraries
for OpenGL, and if OpenGL support isn't important for your project anyways,
just modify the "Makefile.bc" in the fox-0.99.xxx\tests subdirectory so that
it doesn't try to build the "glviewer.exe" or "gltest.exe" examples.


Building FOX as a DLL
=====================

The FOX library can also be built as a DLL for Windows; this is done by
selecting the "foxdll" project and building it. Building this project
causes the import libraries and DLLs to be placed in fox/lib.
The filenames are foxdll.lib and foxdll.dll for the Release build, or
foxdlld.lib and foxdlld.dll for the Debug build.

To compile your own FOX applications so that they use the FOX DLL instead of
the static FOX library, be sure to define the FOXDLL symbol in your compiler
flags. Also note that the DLL must be in your search path for the program to
run!


Building FOX using Mingw32
==========================

FOX, and FOX-based applications, can also be built using the Mingw32 compilers
and related Unix-like tools. If you are not familiar with this development
option, but would like to know more, I recommend starting with the Mingw32
FAQ list found here:

    http://members.aol.com/lauram3017/mingw32.html

DISCLAIMER: The process described here has been tested using the B20.1
release of the Cygwin tools and the mingw32 distribution of gcc-2.95.2 (from
Mumit Khan's site), under Windows NT4 SP5. I know already that it won't work
under Win95 (or Win98?) because the TrackMouseEvent() API is not available on
that platform. More recent versions of the Win95/98 DLLs do support a "back
door" to TrackMouseEvent(), and that's what we're using for the standard
Visual C++ builds of FOX; but sadly the header files and import libraries
available for mingw32 don't at this time include this hook for Win95. I
suspect this will be remedied as time goes on.

To get started, you will need to download & install the following packages:

 o  The Cygwin tools (available from http://sourceware.cygnus.com/cygwin)
    or some reasonable substitute. You will at least need a bash-compatible
    shell and GNU make 3.76.1 or earlier;

 o  The latest mingw32 distribution (available from
    http://www.nanotech.wisc.edu/~khan/software/gnu-win32/gcc.html); and,

 o  The latest FOX distribution.

If you want to use OpenGL, you'll also need to download the OpenGL header
files and import libraries for Mingw32; they are *not* a standard part of
the packages listed above. Here is one source for those, based on the SGI
1.2 OpenGL headers:

	ftp://ftp.teleport.com/pub/users/pgarceau

Now, because of some problems with the version of make distributed with
mingw32 (make-3.77) you'll need to use an earlier version of make, such as
the one distributed with the Cygwin tools (make-3.76.1). Ensure that the
correct version of make is picked up by either renaming or deleting the
version of make distributed with mingw32.

Next, unpack the fox distribution somewhere by typing, e.g.,

	tar xzf fox-0.99.120.tar.gz

and then go to the top-level directory of the FOX distribution and type:

	export LD="//C/gcc-2.95.2/i386-mingw32msvc/bin/ld.exe"
	./configure

The setting for LD should point to the 'bin' directory of your mingw32
installation; the example shown assumes that mingw32 is installed under
C:\gcc-2.95.2.

If the configuration process stops rather quickly, right after it prints the
message about "checking whether make sets ${MAKE}", it's picking up the wrong
version of make (see the notes a few paragraphs earlier). If configure stops
after the message "checking for ld used by GCC" you forgot to set the LD
environment variable before running configure.

Once configure has done it's thing, and assuming there were no errors, build
the library and supporting executables by typing:

	make

and then sit back and wait ;)

Building FOX using Cygwin 1.1
=============================

FOX can also be built against the latest net release of Cygwin, available
for download from here:

	http://sourceware.cygnus.com/cygwin/mirrors

It absolutely will not compile with previous releases of Cygwin (i.e.
Cygwin B20.1 or earlier), at least not without a lot of headaches. The
win32api header files distributed with earlier versions of Cygwin were not
up-to-date enough for FOX.

It should compile out-of-the-box by typing:

	./configure
	make

