BINARY INSTALLATION
===================

You may want to check, if you can get installable packages/binaries for 
your operation system under 
http://www.csv.ica.uni-stuttgart.de/vrml/dune/down.html

BUILD INSTRUCTIONS FOR UNIX/Linux:
----------------------------------

The installation procedure of white_dune do not contain a "make install"
process. This is intentional. 
Instead, if you have root, a systemdependend binary package should be build 
and installed, so white_dune is available to the systemdependend 
installer/packing mechanism. 

The building of systemdependend binary packages is done in the "packager" 
directory.

Systems supported by "packager" directory
=========================================

 For MacOSX 10.2 "jaguar" (based on "X11 for MacOSX Public Beta (+ SDK)") use:
     (cd packager/macosx && sh mksit.sh)

 For IRIX 6.5 use (as root):
     (cd packager/irix && sh mkpkg.sh)

 For SUN Solaris 8 use:
     (cd packager/solaris && sh mkpkg.sh)

 For FreeBSD 5.0-RELEASE use (as root):
     (cd packager/freebsd && sh mkpkg.sh)

 For Redhat Linux (and possibly other rpm based systems) use (as root):
     (cd packager/rpm && sh mkrpm.sh)

 For Debian Linux use:
     (cd packager/debian && sh mkdeb.sh)

 For Slackware Linux use:
     (cd packager/slackware && sh mkpkg.sh)

 For gentoo Linux use:
     (cd packager/gentoo && sh mkebuild.sh)

 You will find the binary package files either in /tmp or in the usual 
 systemdependend place like /usr/src/Redhat

Non root or if your Systems is not (yet) supported by the packager directory
============================================================================

To compile under Unix, you need to have OpenGL/Mesa3D and 
Motif/OpenMotif/Lesstif installed. Older versions of Lesstif 
(e.g. 0.92.26 delivered at /opt/sfw under Solaris) can cause problems 
(nothing works if you click to a icon). To avoid this problems you can use 
"sh ./configure --with-buginlesstif", see below.
Someone reported problems with the fileselector in debians lesstif 0.93.18-4
version. Use openmotif instead.

It is recommended to have libjpeg, libpng and zlib installed.

Note, that dune may fail to compile/run with buggy gcc CVS snapshots called 
"gcc-2.96" (to find out run "gcc -v") which is delivered with some older 
Redhat/Linux distributions. See "--with-kgcc" option below.

Dune also may fail to compile with some (all ?) "ecgs" g++ compilers, 
g++ 2.91.66 is the last "ecgs" compiler made (to find out run "g++ -v") 

Dune compiles at least with 
- gcc/g++ 3.2.1
- gcc/g++ 2.95.3
- gcc/g++ 2.95.2
- gcc/g++ 2.8.1
- MIPSpro 7.30 (SGI IRIX)
- Sun WorkShop 6 update 2 C/C++ 5.3 (SUN SOLARIS) (make depend fails (harmless))

If you got a .tar.gz file then you can extract it with

$ gzip -cd white_dune-whatever.tar.gz | tar -xvf -

and change into the main directory with

$ cd white_dune-whatever

If you want to read and write X3D Files via the java translators from
Qiming Wang, you need to download the files from 
   http://ovrt.nist.gov/v2_x3d.html 
and extract them into the directories ./v2x3d and ./x3dv2

If you want to use the faster saxon translator from 
http://users.iclway.co.uk/mhkay/saxon/ and extract saxon.jar into the 
directory ./x3dv2

Use the X3D translators at your own risk !
To avoid dataloss, the temporary .wrl files are kept in the directory /tmp ...

To compile run 

$ rm -f config.cache
$ sh ./configure --with-somethingbelow --without-somethingbelow 
$ make

A typical configure line when compiling on a typical Linux system is

$ sh ./configure --with-optimization --with-buginlesstif


"sh ./configure --help" gives you a list of available options.

There are some unusual options for running configure

--with-buginlesstif        use to avoid bug if you click to a icon and nothing 
                           works
--without-textedit         disable file -> textedit cause it would do not return
--with-blacknwhiteicons    use Barts black and white icons
--with-nebula              use if you want to convert to The Nebula Device
--without-devil            do not use DevIL library to load textureimages
--with-helpurl="helpurl"   URL of the "docs" directory
--with-vrmlnodesurl="vrmlnodesurl"     URL of ISO standard vrml97 node list 
--with-nurbssurfaceprotourl="protourl" URL of PROTO for NurbsSurface
--without-stereo           use if you do not have shutterglases
--with-stereocommand="stereocommand"  how to switch to stereomode, on IRIX 
--with-kgcc                use to avoid the buggy Redhat/SuSE Linux "gcc 2.96"
--with-routeatend 	   write route statement at end in file
--with-krlikeindent        use if you want Kernigan/Richie like indent
--with-eulerrotation       use for euler angles instead of VRML like rotations
--with-dontreplacevrmlscript do not replace vrmlscript: in URLs with javascript:
--with-dontcarefocus       inputdevice actions dont care about window focus
--with-aflock              use Ascention Flock of birds tracker
--with-aflockdebug         use debug messages for Ascention Flock of birds
--with-coredump 	   switch off emergencysave signalhandling
--with-fpuinterrupts       switch on interrupts on invalid fpu operations
--with-optimization        optimize for speed
--with-gprof               compile with support for gprof analyser
--with-efence              use the efence malloc debugging routines
--with-testinmenu          insert a extra menupoint for testing new things
--with-cut                 currently you better use copy/paste/delete instead
--with-textureimagemode    use nonstandard mode field in TextureImage node
--with-vrmlbrowser=vrmlbrowser     VRML browser eg. netscape freewrl lookat...
--with-wwwbrowser=wwwbrowser       www browser eg. netscape mozilla opera...

===================
--with-buginlesstif        
===================

If you click to a icon and nothing works, there is a problem, that seams to 
be related to some lesstif versions. "sh ./configure --with-buginlesstif" will 
use a workaround.

====================
--without-textedit  
====================

Use this as a workaround, if disable file -> textedit do not return. 
This problem has been occured with glXDestroyContext on a radeon graphics 
card on FreeBSD 5.0-RELEASE (possibly this is a bug in the file -> textedit
implementation itself).

=======================
--with-blacknwhiteicons
=======================    

Use Barts black and white icons instead of the normal colored icons.

=============
--with-nebula              
=============

Use if you want to convert to The Nebula Device 3D engine.
With this feature, white_dune joined forces with "SAND dune"
(Save As Nebula Device) by Aaron Cram (based on Stephen F. Whites dune 0.13). 
For more information see http://www.ori.org/~aaronc/code/nebula/

===============
--without-devil
===============

Do not use DevIL library to load textureimages.
The DevIL library is a wrapper library, it can be used to load different 
imageformats like TIFF, BMP, TGA, MNG, XPM, PCX, PNM, etc.
It is not sure, if your target VRML browser support this imageformats,
cause the VRML97 standard only demand support for JPEG and PNG image file 
formats and recommend GIF. 

========================
--with-helpurl="helpurl"
========================               

URL of the "docs" directory. 
Default: "docs" directory of the source package.
also awailable at http://www.csv.ica.uni-stuttgart.de/vrml/dune/docs/

==================================
--with-vrmlnodesurl="vrmlnodesurl"     
==================================

URL of ISO standard vrml97 node list. 

Default: 
http://www.web3d.org/technicalinfo/specifications/vrml97/part1/nodesRef.htm
Download the ISO standard vrml97 pages to avoid unnecessary internet
communication costs.

======================================
--with-nurbssurfaceprotourl="protourl"
======================================

Currently, the VRML200X NurbsSurface node is not supported by all
VRML97 browsers. There are working NurbsSurface implementations 
in the cc3d (blaxxun contact) and cortona VRML97 browsers.
In the docs/vrml200x_nurbssurface directory of the white_dune sources,
there is a javascript implementation of the NurbsSurface node that
works (at least) with the cosmoplayer 2.? VRML97 browser.
When using the VRML200X NurbsSurface node, dune write per default 
a reference to the urn's of cc3d and cortona and the URL of the local File 
with the PROTO of the javascript implementation of the NurbsSurface node. 
You can replace this URL of the PROTO with a other location.

================
--without-stereo
================

If your system is capable to do quadbuffer stereo, but you do not have
shutterglases or a similar technologie, use --without-stereo to disable
the default stereomode.

====================================
--with-stereocommand="stereocommand"
====================================

On some systems, you need a extra command to switch to a quadbuffer stereo
capable visual.

To see your if the current visual is capable for stereo, use the "glxinfo" 
command and look at the "st" column (for details see the manpage).

On some systems, a 1280x1024 resolution mode is not stereo capable.

To switch on a SGI from a 1280x1024 mode to a stereocabable 1024x768 mode, 
use a command like "/usr/gfx/setmon -n 1024x768_96s" or 
"/usr/gfx/setmon -x 1024x768_96s". On some older systems, setmon commands
to switch resolution ("setmon -x") are only accepted from root and the 
X server must be restarted to complete the operation.

For example a SGI Indigo2 IMPACT/1/1/1 ("High Impact") system in 1024x678_76 
videomode can find a visual with quadbuffer stereo, but the monitor must be 
switched to a matching mode with the command: 
"/usr/gfx/setmon -n 1024x768_96s"
Using the --with-stereocommand option, this can be done by starting dune.

===========
--with-kgcc
===========

 If you have the buggy Redhat Linux compilers (gcc CVS snapshot aka "gcc-2.96")
 or buggy SuSE Linux compilers (gcc CVS snapshot aka "gcc-2.96"), use

 $ rm -f config.cache
 $ sh ./configure --with-kgcc
 $ make
 
 The fake "gcc-2.96" compilers have problems to successfull compile code
 with variable argument list (stdarg).

 To install on Linux redhat 7.1 you will find kgcc in a package called 
 "compat-egcs", which need the compat-glibc package (BTW: the lesstif package
 is in the "powertools" directory).

===================
--with-krlikeindent
===================

 Use if you want this 

 Transform {
   children [
     Shape {
       appearance       Appearance {
         material        Material {
         }
       }
       geometry       Cone {
       }
     }
   ]
 }

 Kernigan/Richie like indent (from their C book) instead of this 

 Transform 
   {
   children 
     [
     Shape 
       {
       appearance       Appearance 
         {
         material        Material 
           {
           }
         }
       geometry       Cone 
         {
         }
       }
     ]
   }

 indent.

=================
--with-routeatend
=================

Write ROUTE statements at the end of the VRML file. 
Otherwise (default) ROUTE statements are written at the first possible
place outside nodes.

====================
--with-eulerrotation
====================

Use if you want to input euler angles (in degrees) as fieldvalues instead 
of VRML like rotations. 
Of course, this option only affects interactive input, not the export or 
import of VRML files.

============================
--with-dontreplacevrmlscript
============================

Some older VRML editors (like cosmoworlds 1.02) use "vrmlscript:"
instead of "javascript:" to sign URL with inlined javascript in Scriptnodes.
If this configure option is not set, white_dune will replace "vrmlscript:" 
with "javascript:" in URLs (to avoid problems with modern VRML browsers).

====================
--with-dontcarefocus
====================

Inputdevice actions dont care about window focus.
This can be useful in situations, when you only work with one dune window
and the inputdevices are used by other people.

=============
--with-aflock
=============

Use Ascention Flock of birds magnetic tracker. 
This is a typical VR inputdevice. If you don't know, if you need this option:
Usually, you only will have a Flock of birds, if your screen is bigger than 
about 1 meter 8-)

==================
--with-aflockdebug         
==================

Use debug messages for Ascention Flock of birds

===============
--with-coredump
===============

Switch off emergencysave signalhandling.
Useful for testing, or if the signalhandling code do not match your system. 

====================
--with-fpuinterrupts
====================

Switch on interrupts on invalid fpu operations. 
Useful to find numeric errors together with "--with-coredump".

===================
--with-optimization
===================

Optimize for speed.

============
--with-gprof
============

Compile with support for the gprof analyser to messure how much time
has been spend in various regions of the code.
After run, a file gmon.out will occure. See the messure with "gprof dune".

=============
--with-efence
=============
             
Use the efence malloc debugging routines. 
This is useful to find hard to find bugs related to memory allocation. 
Efence requires to start dune from the debugger.

=================
--with-testinmenu
=================

This option is only intented for developers of new code, who want to check new 
but do not want to take care about the menu mechanisms.
Look for MainWindow::testInMenu() in MainWindow.cpp to see how to use this 
menupoint.

==========
--with-cut
==========

Tries to make use of the "edit -> cut" menupoint in dune. This is known
to cause problems. Currently you better use the copy/paste/delete 
menupoints instead. Use this option only, if you want to try to write a bugfix.

=======================
--with-textureimagemode
=======================

Dune can use a nonstandard "mode" field in the TextureImage node.

============================
--with-wwwbrowser=wwwbrowser
============================

Use this to configure your default wwwbrowser to view HTML (help) files. 
Examples are netscape mozilla opera etc.

==============================
--with-vrmlbrowser=vrmlbrowser
==============================

Use this to configure your default vrmlbrowser to view VRML files.
This can be needed if your default wwwbrowser (like netscape) has no 
vrml plugin (like the one from FreeWRL) installed and you use a 
standalone vrml browser program (like lookat) instead.

==========================================================================

BUILD INSTRUCTIONS FOR WIN32 (Micro$oft Visual C++ 6.0):
-------------------------------------------------------

Run one of the following scripts in white_dune_directory\batch

nt.bat          (version without the need of the DevIL library)
devil.bat       
devilbw.bat     (version with Bart's black and white icons)
germankides.bat (version with a simplifed modeller menu in german language)

if you do not use nt.bat, you need to install DevIL from 
http://openil.sourceforge.net

If you want to change the parser.y/lexer.l files, you need to install the
cygwin programs "bash", "flex" and "bison" from http://www.cygwin.com/
and need to customise the batch files white_dune_directory\batch\usebison.bat 
and white_dune_directory\batch\useflex.bat

In case of the build command finds no bash, flex and bison tools, the output
previously generated under Linux/Unix/MacOSX will be used.

If you want to read and write X3D Files via the java translators from
Qiming Wang, you need to download the files from 
   http://ovrt.nist.gov/v2_x3d.html 
and extract them into the directories ./v2x3d and ./x3dv2

If you want to use the faster saxon translator from 
http://users.iclway.co.uk/mhkay/saxon/ and extract saxon.jar into the 
directories ./x3dv2

Open the dune.dsw workspace file, and custumise the include/link paths
to Devil. 

The defaults are: 

white_dune_directory\..\devil\include 
white_dune_directory\..\devil\lib

Then select "build dune.exe" from the build menu.
You will find the executable either in the directory Debug or Release.

==========================================================================

MUFTI (mufti@csv.ica.uni-stuttgart.de)
