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

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

  o LINUX
  o Windows NT 4, Windows 9x (VC++, Cygnus, Borland)
  o Digital Unix [Alpha CPU] 3.2, 4.0x
  o SGI IRIX 5.3, 6.1, 6.2, 6.4, 6.5 (MIPS Pro)
  o SUN Solaris, SunOS (gcc, SUN WorkShop Compiler)
  o HP-UX 9.x and 10.x
  o AIX 4.2
  o FreeBSD



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.0 and Mesa 3.0.  It is known to work with older versions of RedHat
or Mesa.  I recommend Mesa 2.6 or above, as FOX will take advantage of the Mesa 
``swap-hack'' to increase redrawing performance.

If you don't care about 3D programming, you will not need Mesa but you need
to configure as:


  ./configure --with-opengl=no
  

Configure will normally detect presence of Mesa, and FOX will automatically take 
advantage of some Mesa-related optimizations such as the swap-hack, which is essentially 
a trick to repaint the 3D window by means of blitting back the information from the
back buffer;  no OpenGL commands are needed to regenerate the picture.

With the advent of OpenGL hardware acceleration under Linux, it is no longer
appropriate to use the swap-hack feature.  If you have such a system, then you
should configure with:


  ./configure --with-opengl=opengl


This basically forces the FOX build to make no special Mesa optimizations even
though the presence of Mesa is detected.


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.  This way, the right compiler will be used.



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
=======================

The Windows 95/98/NT port of FOX can be built either for the Win32 API
(the "native" version) or for X-Windows (using Hummingbird's Exceed XDK).
We currently build FOX on a regular basis using Microsoft Visual C++ 6.0.
There is also support for Cygwin/EGCS 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. Since the native Windows version is still under development, it is
    not the default selection. To build the "native" Windows version,
    be sure to define the symbol FX_NATIVE_WIN32 on your compiler's
    command line. If you omit this parameter, the library will assume
    the Exceed XDK is installed on your machine and attempt to use X calls.
    At some point in the near future, when the native Windows version is
    on par with the X version and becomes the preferred version under
    Windows, this FX_NATIVE_WIN32 business will probably go away.

 2. 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.

 3. 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.

 4. 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++ Builder
=================================

To build it using Borland C++ Builder 3 or later, change to the
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. You want to be sure to have the
updated OpenGL SDK for Win95/NT (including the OpenGL 1.2 header files
and Borland-friendly import libraries). If you don't have this stuff,
and if OpenGL support isn't important for your project anyways, just
modify the Makefile.bc in the tests subdirectory so that it doesn't try
to build glviewer.exe or gltest.exe.


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 the Cygwin tools
===================================

FOX, and FOX-based applications, can now be built with gcc/egcs in
conjunction with the Cygwin tools. Because the header files and import
libraries distributed with the B20.1 release of the Cygwin tools are a
bit out-of-date for FOX's needs, you will need to jump through a few
hoops to get things working. The B21 release (whenever that comes around)
will include the updated headers and import libraries and so things will be
a little easier at that point.

DISCLAIMER: The process described here has been tested using the B20.1
release of the Cygwin tools and gcc-2.95 (from Mumit Khan's site), under
Windows NT4 SP3. 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
gcc/egcs 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 latest FOX distribution;
 o  The Cygwin tools (available from http://sourceware.cygnus.com/cygwin)
 o  Anders Norlander's latest replacement header files and import libraries
    (available from http://www.acc.umu.se/~anorland/gnu-win32/w32api.html)

Another imporant site to add to your bookmarks, if it's not there already,
is Mumit Khan's GNU-Win32 page:

	http://www.xraylith.wisc.edu/~khan/software/gnu-win32

but you already knew that.

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

	tar xzf fox-0.99.78.tar.gz

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

	./configure

By default we're going to compile things to use the Cygwin runtime libraries.
If you would instead like to go the MingW32 route, keep reading and we'll get
there eventually.

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

	export CXX="c++ -I/usr/local/include"
	export CXXLD="c++ -L/usr/local/lib"
	make

The include path and library paths specified here should point to whereever
you installed the w32api headers and import libraries; on my system, they
are installed under /usr/local. You *must* specify these locations as shown;
otherwise the compiler will look at the standard Cygwin distribution's header
files which are too old for FOX's needs.

And now about building with MingW32. For an in-depth discussion of why you
would want to do this, see the various articles on Mumit Khan's web page
(URL listed earlier). The bottom line is, you can use the Cygwin tools (and
gcc/egcs) to build executables that do not depend on the Cygwin runtime
libraries and hence are not subject to any of Cygnus' licensing restrictions.
To specify the use of MingW32, configure the build as follows:

	export CC="gcc -mno-cygwin -I/usr/local/include"
	export CXX="c++ -mno-cygwin -I/usr/local/include"
	export CXXLD="c++ -mno-cygwin -L/usr/local/include"
	./configure --disable-shared --with-mingw32=/usr/local/mingw

where the path specified in the "--with-mingw32" option is the path to the
Mingw32 header files and import libraries. Once configure is finished doing
its thing, build the library and supporting executables by typing:

	make

Currently, it will fail to build the OpenGL test programs (gltest.cpp and
glviewer.cpp). There is no technical problem here, it's just a (hopefully
simple) conflict between header files which will hopefully be resolved "real
soon now".

