Silo Development FAQ
--------------------
1) make errors
   Some file timestamps become an issue, because of the ClearCase file
   write protection on non-checkedout files, there will be errors in
   the build because of these make dependencies. Most of these files
   can be created manually, by looking at the creating scripts in the
   Makefiles. (useful command: force a timestamp update "ct ci -ident")
   make sure that the timestamps of:
   - Autoreconf files, just make sure of the ClearCase checkin order
   ./configure       > ./configure.ac
   */Makefile.in     > */Makefile.am
   - Targets in tests, used by autotest (i.e., make check)
   tests/package.m4  > ./configure.ac
   tests/testsuite   > tests/testsuite.at
   - Target in src/silo/Makefile,
   src/silo/silo.inc > src/silo/silo.h
   src/silo/silo.inc > src/silo/silo_f.h

2) Maintainer mode
   The "missing" script is a wrapper around several maintainer tools,
   designed to warn users if a maintainer tool is required but missing.
   Typical maintainer tools are "autoconf", "automake", etc. Because
   file generated by these tools are shipped with the other sources of a
   package, these tools shouldn't be required during a user build and
   they are not checked for in "configure".
   However, if for some reason a rebuild rule is triggered and involves
   a missing tool, "missing" will notice it and warn the user. Besides
   the warning, when a tool is missing, "missing" will attempt to fix
   timestamps in a way which allow the build to continue. For instance
   "missing" will touch "configure" if "autoconf" is not installed.
   When all distributed files are kept under ClearCase, this feature
   of "missing" allows user with no maintainer tools to build a package
   off ClearCase, bypassing any timestamp inconsistency implied by
   "cleartool checkin".
   If the required tool is installed, "missing" will run it and won't
   attempt to continue after failures. This is the correct behavior during
   development. However, users with wrong versions of maintainer tools
   may get an error when the rebuild rule is spuriously triggered, halting
   the build.
   The rebuild rules are disabled by default, hence all autotools must be
   manually run (usually through, "config/bootstrap" script). Running
   "./configure --enable-maintainer-mode", will enable the automatic
   rebuild rules in Makefile's, which will maintain consistency between
   the autogenerated files. This feature totally automates the running of
   maintainer tools. In maintainer mode should just be able to run "make"
   as it should recognise that Makefile.am, etc. has been modified and run
   the appropriate commands to regenerate the Makefile.
   1) you must put the current autotools binaries in your PATH: 
      PATH=/groups/visit/miller/silo/autotools/linux-x86_64/bin:$PATH
   2) check-out all of the autotools generated files:
      config/bootstrap -o
   3) Enable maintainer tools:
      ./configure --enable-maintainer-mode
   4) development 
      . . .
      to regenerate all autotools generated files:
      config/bootstrap 
      . . .
   5) Disable maintainer mode for distribution:
      ./configure
   6) check-in of the changed autotools generated files:
      config/bootstrap -i "check-in change comments"
  
2) Distributions 
   Automake generates rules to provide archives of Silo for distributions 
   in various formats. Their targets are: 
       dist-bzip2   Generate a bzip2 tar archive of the distribution. 
                    bzip2 archives are frequently smaller than gzipped 
                    archives. 
       dist-gzip    Generate a gzip tar archive of the distribution. 
       dist-shar    Generate a shar archive of the distribution. 
       dist-zip     Generate a zip archive of the distribution. 
       dist-tarZ    Generate a compressed tar archive of the distribution. 
   The rule "dist" by default executes the dist-gzip target. The files is 
   named based on the PACKAGE and VERSION variables, and the gzip'd tar
   file is named "PACKAGE-VERSION.tar.gz". PACKAGE is defined as "silo"
   in configure.ac, along with VERSION. VERSION is release specific usually
   defined as something like "5.0.0". The archive will be extracted into
   the directory "PACKAGE-VERSION".
   To override the default naming and create a distribution "test-test"
   do something like:
      make PACKAGE="test" VERSION="test" dist

3) Installs
   By default, `make install' will install all the files in `/usr/local/bin',
   `/usr/local/lib' etc.  You can specify an installation prefix other than
   `/usr/local' using `--prefix', for instance `--prefix=$HOME'.
   Alternatively, You run the normal build procedure until you get to the 
   install target: 
      ./configure 
      make 
   Instead of calling 'make install' you can add a DESTDIR flag which will 
   prepend the normal PREFIX (must be an absolute directory name), like
   follows: 
      make DESTDIR=`pwd` install 
   This will install all the files (libraries, includes, binaries) at the 
   level of the current directory. 
   Automake generates separate install-data and install-exec rules, in case 
   the installer is installing on multiple machines that share directory 
   structure--hese targets allow the machine-independent parts to be 
   installed only once. install-exec installs platform-dependent files, 
   and install-data installs platform-independent files. The install target 
   depends on both of these targets. 
   Variables using the standard directory prefixes "data", "info", "man",
   "include", "oldinclude", "pkgdata", or "pkginclude" are installed by
   install-data. 
   Variables using the standard directory prefixes "bin", "sbin", "libexec",
   "sysconf", "localstate", "lib", or "pkglib" are installed by install-exec. 

4) clearmake
   Clearmake has it's own idea of computing dependencies, it is pretty much
   a special file system tracking all of the reads, writes, etc, and feeding
   that information back into clearmake.
   Automake on the otherhand, not nearly as complex an application, generates
   dependencies as a side effect of complation.
   Clearmake doesn't follow the automake defined dependencies.
   Clearmake's dependency tracking does appear to function in parallel with
   the current silo automake configuration.
   To use clearmake:
   1) you must put the current autotools binaries in your PATH: 
      PATH=/usr/gapps/silo/autotools/i686-pc-linux-gnu:$PATH
   2) checkout all of the autotools generated files:
      config/bootstrap -o

5) Configure
   Variables not defined in a site shell script can be set in the environment
   passed to configure.  However, some packages may run configure again during
   the build, and the customized values of these variables may be lost. In
   order to avoid this problem, you should set them in the configure command
   line, using "VAR=value". For example: 
      ./configure CC=/usr/local/pgi/linux86/6.0/bin/pgcc
   causes the specified Portland Group C to be used as the C compiler.
   Run "./configure --help" for details on some of the pertinent environment
   variables.
   Other examples:
     ./configure --prefix=/usr/gapps/silo/4.5.1-pre4/i386-pc-linux-gcc-3.2.3 \
     --with-szlib=/usr/gapps/silo/szip/2.0/i386-pc-linux-gcc-3.2.3 \
     --with-hdf5=/usr/gapps/silo/hdf5/1.8.0-beta3/i386-pc-linux-gcc-3.2.3/\
include,/usr/gapps/silo/hdf5/1.8.0-beta3/i386-pc-linux-gcc-3.2.3/lib \
     --enable-silex \
     --with-Qt-dir=/usr/gapps/silo/qt/3.3.8/i386-pc-linux-gcc-3.2.3 
