EQUIP
Chris Greenhalgh - cmg@cs.nott.ac.uk
27/3/2001; last updated 140601

** this file is in cvs - ./Equator/BuildNotes.cmg ** 

Local notes: at Nottingham you may well be able to use the version(s)
of NSPR, Bamboo and other external things in /mrl/src/Equator/shared.
Just make you own Modules directory (in your own project area, for
development work) and set up a suitable configuration for bamboo and
build any extra equip modules.
(/mrl/src/Equator/shared/Equator/Bamboo/config should be writable for
group crg)

Remote notes: hopefully the CVS server is now working. Set the CVSROOT
environment variable to 
':pserver:anonymous@dumas.mrl.nott.ac.uk:/mrl/src/cvsroot'
and try 'cvs login'. 

There are some tar file snap-shots available if the contents of the
CVS server; these make a good starting point, even if you then 
update them to get newer stuff. The current split (8/6/01) is:
 * Equator-Bamboo-080601-src.tar.gz - Equator/Bamboo source
 * Equator-NSPR-080601-src.tar.gz - Equator/NSPR source
 * Equator-Modules-080601-src.tar.gz - Equator/Modules source, 
including crg (CRGSHARE), massive3 and equip (main EQUIP release).
 * Equator-other-080601-src.tar.gz - other Equator subdirectories,
including Audio, helpers, docs.
 
see http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases

======================================================================
1) NSPR

  The C/C++ part of EQUIP uses Bamboo that in turn uses NSPR 
  (Netscape's Portable Runtime). You need a binary distribution of NSPR
  for your platform. Some complete builds are available. Otherwise
  you should get the source and compile it.

  Download:

    win32 build available as:
	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/external/nspr-win32-dbg.tar

    (untar in ./Equator/NSPR to give ./Equator/NSPR/dist which is what
    you would get if the build 1.1-1.4 worked)

  Or Build:

    or if that is no good you need to compile it (1.1-1.4)...

1.1) get source:

   Do either (a) or (b):
   a) 	download Equator-NSPR-080601-src.tar.gz, uncompress and
	extract in .
	> gunzip -c Equator-NSPR-080601-src.tar.gz | tar xf -
	to give Equator/NSPR/nsprpub
	
    b)  alternatively, use the CVS server (set up as at the top),
	in .
	> cvs checkout Equator/NSPR

    If you want to check that your source (obtained as above) is
    up to date then try (in Equator/NSPR/nsprpub):
   	> cvs status
    and if you want to get changes:
	> cvs update

1.2) get build tools:

    On Win32 you need appropriate unix-like build tools, which
    Netscape/Mozilla make available as 'moz_tools.tar'. 

    On UNIX you need some standard stuff (gmake, etc.) (check
    the READMEs and build notes in the source distribution).

    Win32: 
	moz_tools.tar (Win32 only) is available as:
	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/external/moz_tools.tar

    	(original: ftp://ftp.mozilla.org/pub/mozilla/source/wintools.zip)

    	extract in directory ./external (create this directory if necessary).
    	to give ./external/buildtools and ./external/moz_tools

1.3) Check/set build environment, 
    e.g. on WIN32:

	check ./Equator/NSPR/mozenv.bat and source. 

	    > mozenv

	Also set vars for c++ (vcvars32.bat - in vc++ bin dir.)

 	    > vcvars32

1.4) Compile and install:

    in ./Equator/NSPR/nsprpub

	> gmake

======================================================================
2) Bamboo

  EQUIP uses Bamboo for its build environment and the C/C++ part 
  also uses Bamboo for dynamic code loading. In the future EQUIP 
  may also use dynamic code loading across the network via Bamboo.

  You need a binary distribution of Bamboo
  for your platform. Some complete builds are available. Otherwise
  you should get the source and compile it.

  Even if you download a build rather than compile from source you should
  still set up your bamboo development environment (steps 2.3 & 2.4). 
  Also, for Win32, you also need the support tools (step 2.2).

  Download:

    complete win32 build available as:
  	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases/Equator-Bamboo-080601-win32.tar

    (untar in ./Equator to give ./Equator/Bamboo)

    Now do steps 2.2 (build tools), 2.3 (configure for building and
    running modules) 2.4 (configure bamboo for building).


  Or Build:

    or if that is no good you need to compile and configure it (2.1-2.6)...

2.1) get source

   Do either (a) or (b):

   a) 	download Equator-Bamboo-080601-src.tar.gz, uncompress and
	extract in .
	> gunzip -c Equator-Bamboo-080601-src.tar.gz | tar xf -
	to give Equator/Bamboo
	
    b)  alternatively, use the CVS server (set up as at the top),
	in .
	> cvs checkout Equator/Bamboo

    If you want to check that your source (obtained as above) is
    up to date then try (in Equator/Bamboo):
   	> cvs status
    and if you want to get changes:
	> cvs update


2.2) get build tools:

    On Win32 you need appropriate unix-like build tools (different
    from those for NSPR!!); we (Equator) are currently using an
    older (Feb 2001) release of Bamboo. We also have our own 
    updared version of the build tools, so use the download below 
    rather than the current/old Bamboo ones.

    On UNIX you need some standard stuff (gmake, etc.) (check
    the READMEs and build notes in the source distribution).

    Win32:
	equator-bamboo-tools.tar.gz (win32 only) is available as:
	    http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/external/equator-bamboo-tools.tar.gz

	extract in directory ./external
	to give ./external/equator-bamboo-tools

2.3) Set up your environment for building and running Bamboo

    Win32:
	see ./Equator/Modules/bbenv.bat

	[this is missing from some pre-builds, but is present in
	the full source, in CVS and in the Equator web docs 
	directory, 
	 http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/docs]

	See also the online bamboo build notes (www.watsen.net/Bamboo).
	Bear in mind that different variables are used by different 
	commands, with varying requirements for paths (/, \, C:, ;, :, ...).

	Also be sure that visual c++ (pref. v6, sp4 or above) can be found
	from the shell (see step 1.3).

    UNIX:
	see ./Equator/Bamboo/bbenv.cshrc (?)

2.4) Configure bamboo

  To use bamboo, especially to compile, you must set up a machine-specific
  configuration file (in ./Equator/Bamboo/config). To do this you can either
  use Bamboo's config system, or copy and modify by hand an existing 
  configuration. I recommend you try modifying an similar sample first.

  Either:

    a)	go to ./Equator/Bamboo/config and copy a config file from a 
     	similar machine (OS, etc) and edit by hand
     	
	Win32: be careful with the visual C++ options; typically go
		for RTTI, exceptions, multi-threaded DLL (/MD).

    b)  or, use the bamboo config system: in ./Equator/Bamboo

	    > gmake config

     	and check generated file ./Equator/Bamboo/config/bbdefs_host_<OS>_<NAME>

	Win32: see the notes by (a).


2.5) Compile

  in ./Equator/Bamboo

	> gmake compile

2.6) Check environment for running:

     Revisit step 2.3. In particular, ensure that BB_MODULE_PATH 
     is set correctly, including
     ./Equator/Modules AND ./Equator/Modules/equip

     Revisit step 2.4. and double check.


======================================================================
Pre 3)

   Get the source (whatever you plan to do - other parts will be needed);
   Do either (a) or (b):

   a) 	download Equator-other-080601-src.tar.gz, uncompress and
	extract in .
	> gunzip -c Equator-other-080601-src.tar.gz | tar xf -
	to give Equator/Bamboo
	
    b)  alternatively, use the CVS server (set up as at the top),
	in .
	> cvs checkout Equator/libIDL Equator/Audio Equator/helpers
	> cvs checkout Equator/docs Equator/Http

======================================================================
3) libIDL and eqidl - idl compiler

  Adding/compiling new sharable data types requires eqidl, the Equator
  IDL compiler. This is based on a MODIFIED version of libIDL-0.6.8
  for IDL parsing. This in turn relies on glib.

  You need a binary distribution of eqidl and supporting dynamic
  libraries (e.g. modified libIDL, glib) for your platform. 
  Some complete builds are available. Otherwise you should get 
  the source and compile it.

  Download:

    Win32: 
	glib1.2 win32 available as:	
    	    http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/external/glib1.2-win32.tar

	(untar in ./external -> ./external/glib1.2-win32


	eqidl.exe and libIDL win32 available as:
	    http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases/Equator-libIDL-080601-win32.tar.gz

	(untar in . -> ./Equator/libIDL/libIDL-0.6.8/... eqidl.exe and libIDL-0.6.dll)
	
  Or Build: (3.1-3.4)

3.1) get source

	See pre 3), above.

3.2) get glib

	get libs, dlls and includes and install it somewhere

	Win32: 
	    get glib1.2-win32.tar (above) and untar into ./external -> 
	    ./external/glib1.2-win32
	

3.3) Configure

    Win32: 
	edit libIDL makefile, 
	    ./Equator/libIDL/libIDL-0.6.8/Makefile.msc
	e.g.
	    set BIN = J:\dev\external\glib1.2-win32\bin
	    # GLib location
	    GLIB_INCLUDES = -IJ:\dev\external\glib1.2-win32\include
	    GLIB_LIBPATH = J:\dev\external\glib1.2-win32\lib
	    GLIB_LIB = glib-1.2.lib

    UNIX: 
	check the build documentation; use configure and that kind
	of thing.

3.4) compile

    Win32:
	in ./Equator/libIDL/libIDL-0.6.8
	> nmake /fMakefile.msc

	depending on the platform you may need to change lexer.c


    Unix:
	make ?
	I haven't done non win makefile updates.


======================================================================
4) EQUIP and other modules

  EQUIP itself is in ./Equator/Modules/equip. It comprises a number of 
  bamboo modules, each with Java and C++ source. 

  Some EQUIP modules also make use of other modules, in particular:

  o ./Equator/Modules/crg is a subset of Uni.Nottingham's CRGSHARE
    library, and includes a renderer used by equip_draw3d_dgl and 
    massive3.
 
  o ./Equator/Modules/massive3 is a subset of Uni.Nottingham's
    massive3 CVE system, and is used by equip_draw3d_mas3 (and to run
    massive3 directly).

  You should normally aim to build these modules, although pre-compiled
  versions may be available. It is quite acceptable to share module
  builds (and equip releases) using a networked filesystem. E.g. all 
  local users at Nottingham may share Bamboo, NSPR and core modules
  on /mrl/src/Equator/shared

  Win32 precompiled (debug):

    Equator/Modules/crg:
	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases/Equator-Modules-crg-080601-win32.tar.gz

    Equator/Modules/massive3:
	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases/Equator-Modules-massive3-080601-win32.tar.gz

    Equator/Modules/equip:
	http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/releases/Equator-Modules-equip-080601-win32.tar.gz

  With Bamboo correctly configured (steps 2.4 & 2.6) compiling a module
  should just be a matter or running 'gmake compile' in the module's
  directory.

4.1) get source

   Do either (a) or (b):

   a) 	download Equator-Modules-080601-src.tar.gz, uncompress and
	extract in .
	> gunzip -c Equator-Modules-080601-src.tar.gz | tar xf -
	to give Equator/Modules
	
    b)  alternatively, use the CVS server (set up as at the top),
	in .
	> cvs checkout Equator/Modules

    If you want to check that your source (obtained as above) is
    up to date then try (in Equator/Modules or the relevant sub-
    directory):
   	> cvs status
    and if you want to get changes:
	> cvs update


4.2) compile

    If you expect to use audio and/or dgl 3d graphics then compile
    crg first:

	in ./Equator/Modules/crg:
	> gmake compile

    If you expect to use Massive3 and/or mas3 3d in equip then 
    compile massive3 next:

	in ./Equator/Modules/massive3
	> gmake compile

    If you wish to use the vrjuggler 3d renderer then jump forward and
    do 7 and then come back.

    Now compile equip itself:

	in ./Equator/Modules/equip
	> gmake compile

	this may bomb out part way through depending other module 
	dependencies. In this case try the individual module builds.
	A possible partial build order is:

		equip_runtime
		equip_net
		equip_net_Trader
		equip_data
		equip_data_Server
		equip_data_Test (optional)
		equip_math
		equip_input
		equip_service
		equip_mas3_control
		equip_audio
		equip_video
		equip_video_Server (optional, win32)
		equip_audio_CrgPeer (optional, uses crg audio)
		equip_draw3d
		equip_display3d

		equip_draw3d_dgl (requires crg)
		equip_display3d_dgl (requires crg)
	...

======================================================================
5) crg 

   see 4)

======================================================================
6) massive 

   see 4)

======================================================================
7) vrjuggler 

  The EQUIP renderer equip_display3d_vrjuggler requires a suitable
  build of U.Iowa's VRJuggler before it can be build. VRJuggler is 
  available from www.vrjuggler.org.

  The bamboo module version of vrjuggler has been withdrawn for the
  time -being (it was based on version 0.1.97, whereas we currently
  are using the 1.0.0 release).

  Win32: 
	You will need to compile from source, changing the MSVC++
	compile flags from to /MDd or /MD (threaded, DLL runtime).

	Or try downloading (debug on build)
	    http://www.crg.cs.nott.ac.uk/~cmg/Equator/Downloads/external/vrjuggler-1.0.0.win32MD.tar.gz

	and jump to stage 7.2.

7.1) compile

  Configure and compile vrjuggler as explained in its own documentation.

7.2) configure environment

  Be sure that VJ_BASE_DIR is correctly set to run vrjuggler and before
  building equip_display3d_vrjuggler.

7.3) compile equip renderer

  You should now be OK compiling the module 
	./Equator/Modules/equip/equip_display3d_vrjuggler

7.4) update vrjuggler's configuration

  equip_display3d_vrjuggler also uses new vrjuggler input devices,
  EquipAnalog and EquipDigital; to use these you must add the 
  corresponding info (from 
  Equator/Modules/equip/equip_display3d_vrjuggler/chunksDesc) to 
  your vrjuggler installation ($VJ_BASE_DIR/share/Data/chunksDesc).

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