
This file contains an overview of the build process and describes useful
information for developers and advanced users.  If you encounter difficulties
in building meshtv this file may also be useful if you wish to solve the
problems yourself.  If you wish to build or install meshtv you should start
with `INSTALL_NOTES'.


Overview of the build process
=============================

The build process consists of the following steps.

1) Run configure to analyze the operating system and machine architecture
   and then configure system dependent files and build the Makefiles.

2) Run make to compile and load the distribution.

3) Install libraries and header files into public directories or build a
   meshtv distribution file.

If you are a developer you can also use autoconf to regenerate the
configure script.


Configure
=========

Most users should be able to say just:

    $ ./configure

If you are a meshtv developer and have written a site
configuration file for meshtv in the "config-site" directory, then
you might want to say this instead:

    $ env CONFIG_SITE=config-site/`hostname` ./configure

or move the appropriate site configuration file to
/usr/local/etc/config.site and then just say "./configure".


If you are installing on a system which has the GNU compiler
installed incorrectly then you might have to force configure to
use "cc" as the compiler.  Say this:

    $ env CC=cc ./configure

If you are installing on a system which has the GNU readline
header files or library installed incorrectly and you wish to
compile/install MeshTV without fixing your system, then say

    $ ./configure --without-readline

If your X11 include files and/or libraries are in a strange place
then you might have to tell configure where they are.  For
instance, on spear.llnl.gov the include files are under the
/usr/local/motif directory under usr/include and the libraries
under usr/lib.  Configure would be invoked as:

    $ ./configure --x-includes=/usr/local/motif/usr/include \
                 --x-libraries=/usr/local/motif/usr/lib

If X/Motif libraries are split among more than one directory, then
just list all necessary directories separated by spaces like this
example:

    $ ./configure --x-includes="/usr/include/X11R5 /usr/include/Motif1.2" \
                 --x-libraries="/usr/lib/X11R5 /usr/lib/Motif1.2"


If you are installing on Linux and need to cross compile to a.out
format and statically link because you have an old Motif library then
say:

    $ env CFLAGS="-b i486-linuxaout -static -O2" ./configure


If you say "make install" later, then executables, include files, and
libraries are installed under the prefix "/usr/local".  To change this
to some other directory, DIR, add "--prefix=DIR" to the end of the
configure command line.  You don't have to "make install" if you just
want local copies of the executables, include files, and libraries.
Please refer to the INSTALL file for other configure options or
type "./configure --help"

The configure script will check for the -lGL library and use the
OGL driver if the library is found.  As a last resort, the X11 driver
is used.  Checking for the OGL library can be disabled by adding the
following flag to the end of the configure command line:

    --disable-ogl

If you choose to use the GNU make and it's installed under a
different name than "make" you may have to add "MAKE=gmake" before
the configure.  Using GNU make will cause configure to build
Makefiles with rules that are inappropriate for other make's.

If you are building on a system that has the Powerwall VDL Library
available then you should first set the VDL environment variable
to the directory where VDL is installed. Note that in the following
example, vdl_directory would be replaced with the path of the VDL
installation on your system.

    $ env VDL=vdl_directory ./configure

When the VDL environment variable is set, configure will build the
powerwall related code and attempt to link with the VDL library.
The directory used for vdl_directory must contain "include" and
"lib" or "lib64" directories. If you are building the parallel
version of MeshTV with VDL enabled, it is recommended that you
build the 64 bit version to cope with large data sizes.

Make targets
============

$ make

    Build the libraries and executables.  It also copies meshtv public
    header files to the meshtv/include directory before compiling.

$ make depend

    Build the dependency lists for the Makefiles.

$ make install

    Install the public header files, libraries and executables in their
    permanant homes in the directories $(prefix)/include, $(prefix)/lib and
    $(prefix)/bin, respectively, where $(prefix) is "/usr/local" unless it
    was changed when the Makefiles were configured.

$ make install_bin

    Only install the executables.

$ make install_lib

    Only install the libraries and header files.

$ make check

    Run any self tests that come with the package.

$ make clean

    Clean up any object files, libraries and executables.  This target may
    generate a lot of error messages since packages like "meshtvx" depend
    on previous packages like "silo".  The top-level Makefile invokes
    sub-makes in the opposite order as the "make install" in an atttempt to
    reduce the number of error messages.

$ make distclean

    Clean up any object files, libraries, executables, Makefiles, and
    files created by configure.  This can be used to do clean up before
    doing clean build from scratch.

$ make maintainer-clean

    Clean up any files which can be automatically generated.  This should
    be used with extreme caution.  If you do not have the GNU autoconf suite
    of programs, you should not use the maintainer-clean target.


Directories
===========


bin                     Temporary home for executable's and shell scripts
include                 All header files, private and public
lib                     Temporary home for all libraries

score                   The score library, a subset of PACT SCORE
pdb                     The pdb library, a subset of PACT PDB

silo                    SILO
silo/silo               The SILO kernel
silo/swat               SILO support functions
silo/netcdf             The SILO netcdf data driver
silo/pdb                The SILO pdb data driver
silo/sdx                The SILO sdx data driver
silo/taurus             The SILO taurus data driver
silo/unknown            The SILO unknown data driver

silo/browser            A SILO file browser
silo/filters            Various SILO filters.
silo/debug              A SILO filter for debugging SILO calls
silo/tests              Test files

spi                     Spi library sources
meshtv                  MeshTV GUI sources
meshtvx                 MeshTV sources


GNU Autoconf
============

MeshTV uses the GNU autoconf suite of programs to generate a `configure'
shell script which when run, creates `FILE' based on `FILE.in' in each
of the source directories (see the bottom of configure.in for a list
of such files).

Before distributing a MeshTV, the developer should type

        $ autoheader          # creates include/config.h.in
        $ autoconf            # creates configure

The GNU m4 program is required for these two commands to succeed.  However,
no special programs are required on the end user's machine when `configure'
is executed.

The `configure.in' file contains information about tests that need to
be performed on the end user's system by configure.
