Compiling the MASSIVE-3 library and/or Applications

Chris Greenhalgh, 6/12/2000, rev-4b.

Supported Platforms

MASSIVE-3 currently has limited cross-platform build support. It has been compiled in the past on IRIX using cc, on AIX using gcc and on Windows using Microsoft Visual C++ version 4.2 and above.

Directory Structure

If you have access to the core MRL directories then you will find that the top level massive3 directory is divided into release directories ('rev-*') and personal development directories ('dev-*'). Within each one the structure is the same. The external tarball release is one such release directory.

Each release/development copy of massive-3 typically include the following top-level directories:

The source code (src) is divided into a number of subdirectories:

Each platform-specific build directory has a parallel set of directories in which libraries/programs are compiled, e.g. on Windows:

plus:

(Being platform independent) src/mgmtjava can be compiled in place.

Makefile Structure

There is slightly odd cross-platform build system as follows.

For each target platform there is a platform-specific Makefile that defines path separators, commands, flags, etc. These can be found in the src/ directory as Makefile-prefix.<TARGET>. For example, Makefile-prefix.win32, Makefile-prefix.unix, Makefile-prefix.aix. Any customisation for a particular build platform should be done here.

For each build directory there is a (hopefully) platform-independent Makefile, just called Makefile (e.g. src/libhivek/Makefile).

Once platform-specific build directories (<PLATFORM>) and subdirectories (bin, libhivek, stdapps, devices, apps, mgmtapi, samples) have been created (by hand), and whenever a Makefile is changed, the real Makefiles are generated from the above using a script run from the platform-specific build directory.

For windows, in the i386-ms-wnt4.0/ directory run:

> ../scripts/win32makefile

This is a Bourne Shell (or BASH) script; it can be run under Cygnus solutions Cygwin UNIX shell (www.cygnus.com, search for Cygwin) on the windows machine, or can be run on a UNIX machine hosting the filesystem. This uses sed to do some of the symbol substitutions that nmake (Microsoft's make) cannot cope with.

For other platforms, in the <PLATFORM> directory run:

> ../scripts/anymakefile <TARGET>

where <TARGET> is the suffix on the platform-specific Makefile that you want to use.

These commands will create the following makefiles:

Building MASSIVE-3

MASSIVE-3 uses several libraries from CRGSHARE. CRGSHARE has its own build system. On UNIX this is based on autoconf; on Windows there is a separate hand-crafted set of Makefiles. If you need to build this for a new platform then good luck...

Once you have a suitable build of CRGSHARE, you can build MASSIVE-3 as follows:

  1. Create the platform-specific build directory if it does not already exist. On windows this is currently 'i386-ms-wnt4.0'; on UNIX platforms it is normally the result of running the script scripts/config.guess. We will refer to this directory name as <PLATFORM>.
  2. Create the build sub-directories if they do not already exist: bin, libhivek, stdapps, devices, apps, mgmtapi, samples
  3. Check the platform-specific makefile prefixes in src/ and find or create one that suits your build platform. We will refere to its filename suffix as <TARGET>.
  4. From the <PLATFORM> directory run the script to create the makefiles as described above, i.e.
    > ../scripts/win32makefile
    or
    > ../scripts/anymakefile <TARGET>
  5. Ensure that your environment variables are set up correctly in the shell in which intend to compile.
    On Windows use a command shell and run the batch file scripts/NTenv.bat that is described in the user tutorial.
    On UNIX make sure that the following environment variables are set:
    PLATFORM - set to <PLATFORM>, above.
    CRGSHARE_VER - set to the full path of the crgshare directory.
    LD_LIBRARY_PATH - set as per the user tutorial, to locate crgshare and massive3 shared objects.
  6. Build the subdirectories in the following order:
    libhivek
    stdapps
    mgmtapi
    apps
    samples
    devices
    stdapps     (2)
    On Windows, cd to each directory in turn and do:
    > nmake all
    On UNIX, cd to each directory in turn and do:
    > make all
    When returning to stdapps at the end use the make target 'immersive', e.g. on Windows:
    > nmake immersive
  7. Check in the bin directory that libhivek and the various executables have been created.
  8. If you want to use the mgmtjava programs then cd to src/mgmtjava and compile everything:
    > javac *.java

Note 1: the build dependencies are not complete; if you change a file, especially in the core library, and you are not sure what depends on it then it is safest to delete all objects and recompile everything.

Note 2: remember to change the Makefiles under src/ and then to rerun the makefile generating script, rather than changing the Makefiles in the individual build directories.