GRUMMP is distributed in source form. The software is 
self-configuring, using a script generated by GNU autoconf. Note 
that autoconf is not required to set up GRUMMP. The primary 
development platform for GRUMMP is Linux, with gcc4; 
unfortunately, we do not currently have access to a wide range of 
platforms for thorough portability testing. However, other Unix 
variants should pose no major problems, especially with GNU 
compilers. In addition, native compilers on the following 
platforms have worked in recent releases and so are expected to 
still work:

  x86 / Linux 2.x with Intel v5.0 compilers

  SGI / IRIX 6.x with MIPSpro v7.4

  Compaq-Alpha-HP / OSF 5.1 with Tru64 v6.5 (tested on a 
  Compaq-branded machine, but they all use Compaq's compiler, so 
  all should be fine, as should Alpha / Linux machines with the 
  Compaq compiler)

  IBM / AIX with xlC

  x86 / Win32 with VC++ 7.1

  x86 / Win32 + Cygwin with gcc. Support here isn't perfect; 
  please report any problems. In particular, it isn't at all 
  clear that shared libraries will work on Cygwin at this point.

On some systems, warnings occur during compilation; none of these 
warnings are thought to affect executable performance. Other 
systems may also work, but have not been tested in some time due 
to lack of access to test machines.

  Getting GRUMMP

GRUMMP is most easily available on the WWW from the GRUMMP home 
page http://tetra.mech.ubc.ca. GRUMMP version 0.5.0 ftp://tetra.mech.ubc.ca/pub/GRUMMP/GRUMMP-0.5.0.tar.gz
 is also available via anonymous ftp. Or you can choose the 
symbolic link to the most recent version ftp://tetra.mech.ubc.ca/pub/GRUMMP/GRUMMP.tar.gz
.

  Building GRUMMP the easy way

Suppose that you download GRUMMP and store the gzipped tar file 
in /home/me. After using gunzip and tar to extract the files from 
the distribution, 

cd /home/me/GRUMMP-0.5.0

Now all you need to do is type

./GRUMMP-build

This runs a shell script that will automatically configure and 
build GRUMMP for your machine, if at all possible. The script 
first attempts to build an optimized version of GRUMMP. If that 
fails, then it tries again without optimization (and with more 
compiler warnings enabled). Any compiler error and warning 
messages are stored in a temporary file. After the script is 
finished building GRUMMP, it summarizes the outcome for you. 

Finally, the script will collect relevant output files and create 
a tar file of them. Email-ing this file to the developers at 
cfog@mech.ubc.ca will help us to improve portability of GRUMMP. 
The tar file contains only output files from configuring and 
building GRUMMP.

  Building GRUMMP under Windows

There is a VC++ project file available in the top-level directory 
of the GRUMMP distribution. In principle, all you should have to 
do is use this project file. Minor problems have been reported, 
however. If you should happen to run into problems (especially if 
you have fixes for them to pass along), please let the developers 
know, as we don't do our own Windows testing in-house.

  Configuring GRUMMP by hand

Under some circumstances, GRUMMP may not build properly 
automatically for reasons unrelated to the source code. The most 
common reasons are the flex/lex libraries are in an odd place, or 
that the native compiler on your machine has an unusual name. In 
these cases, running configure yourself will likely solve the 
problem.

Suppose that you download GRUMMP and store the gzipped tar file 
in /home/me. After using gunzip and tar to extract the files from 
the distribution, 

cd /home/me/GRUMMP-0.5.0

and type 

./configure 

The configure shell script is an automated process for 
determining the type of machine that GRUMMP will be running on 
and the capabilities of the system software on the machine. 

  configure options

  --with-flex-lib-dir=DIRNAME This option is sometimes needed so 
  that configure can find the library libfl.a (flex) or libl.a 
  (lex).[footnote:
flex is used if found; otherwise lex is used. If neither is 
found, then user-defined I/O formats can not be used.
] This option is not needed unless configure exits with a warning 
  about not being able to find these libraries and you want to 
  use user-defined file formats (see Chapter [chap:files]). In 
  this case, re-run configure with the full path for the library 
  using this option.

  --with-c-compiler=NAME 

  --with-cxx-compiler=NAME Specify the compiler name using these 
  options to use a C/C++ compiler other than the native compiler 
  (including gcc/g++), to use a native compiler that is in an 
  unusual place, or to use cc/CC on Sun machines (older Sun 
  machines have a broken native C compiler). Only the name of the 
  compiler is needed if it resides in your usual path. Full path 
  names are accepted, as are relative path names from directories 
  in your default path.[footnote:
For example, /usr/local/lib/cc could be specified as ../lib/cc if 
/usr/local/bin is in your default path. Note that /usr/lib/cc 
would be found instead in this case if /usr/bin precedes 
/usr/local/bin in your path.
] If in doubt, use the full path name. In any event, output from 
  configure will tell you which compiler will be used.

  --with-addl-path=PATH Specify an additional entry for the PATH 
  environment variable. This helps configure find its way to 
  compilers located in odd places. I don't fully understand why 
  this is even necessary, but I had to add it to compile version 
  0.1.7 on one of my test machines.

  --with-debug This option enables careful compile-time checking 
  of the code and run-time verification that is much more 
  extensive than in the optimized version, as well as producing 
  an executable that can be used in conjunction with a debugger. 
  This is primarily a development option, but end-users are 
  occasionally asked to use this option in conjunction with bug 
  reports that can not be reproduced on machines to which the 
  developers have ready access.

  --enable-vtk-input This option makes VTK the default input file 
  format. This option is not generally a useful choice, as VTK 
  doesn't include a variety of useful information, including 
  boundary conditions. This option exists solely to make it 
  easier to run TSTT example programs.

  --enable-itaps This option builds GRUMMP with support for the 
  iMesh interface developed by the Interoperable Tools for 
  Advanced Petascale Simulations (ITAPS) consortium. This API 
  provides low-level mesh query and modification functionality in 
  a data-structure and programming language independent way. See http://itaps-scidac.org
   for more information.

Once configure has finished, type

make -k

This nested make will create all the libraries required by GRUMMP 
as well as the executables.

  Setting LD_LIBRARY_PATH

GRUMMP builds both shared and static libraries. By default, the 
shared libraries are used to create the executables. To be able 
to run these executables, you must add 
/home/me/GRUMMP-0.5.0/lib/lib[gO]/system-type to the environment 
variable LD_LIBRARY_PATH. system-type is a variant on the name of 
your OS. GRUMMP-build and configure print this information at the 
end of its run, including information on how to change the 
environment variable. If in doubt, check to see what directory 
was just created in GRUMMP/lib.

  If Your Machine Is Not Yet Officially Supported<sec:unsupported-machines>

First, go ahead and try to configure and build GRUMMP anyway, 
with this minor variation: use

./configure --with-debug [other config options] >& config-output

This will enable at least some compile-time checking as well as 
enabling debugging. Then build GRUMMP using (with csh-type 
shells)

make -k >& make-output

The last few lines of make-output will tell you whether the build 
was successful. Whether the build is successful or not, please 
mail the following information to cfog@mech.ubc.ca:

  config.status

  config.log

  config.cache

  include/GR_config.h

  make-output

  config-output

  result of uname -a

  If your compiler is not gcc/g++, please also include the parts 
  of your C and C++ compiler man pages that describe 
  optimization, debugging, and enabling warnings. 

This information will be useful in developing full support for 
new systems. In particular, make-output and the information on 
enabling warnings can be used to improve portability; and 
information on compiler optimization flags will improve 
out-of-the-box optimization of GRUMMP.

  If Something Goes Wrong During Setup

  Problems with configure

If configure fails, it will exit with an error message. Please 
report this message to cfog@mech.ubc.ca, along with copies of the 
files config.status, config.cache, and config.log, if they exist, 
and the result of uname -a on your machine. If more information 
is needed to diagnose a misconfiguration problem, you will be 
contacted. configure failures are quite rare: I can only recall 
one so far.

  Problems with make

If make fails, please re-run configure and make as described in 
Section [sec:unsupported-machines] and submit the same 
information requested there. At least some machines may require 
additional configuration support for certain system libraries, 
and this information will help isolate these problems.

  Checking to be Sure Things Built Properly

In the GRUMMP root directory, run 

make test

This will use the newly-created GRUMMP executables to generate 
several meshes in both 2D and 3D, as well as improving a sample 
mesh in 3D. If all has gone well, the only output from this 
command should be:

Testing 2D mesh generation...success 

Testing 3D mesh generation...success 

Testing 3D mesh improvement...success 

Should you get a failure here, please report it to the 
developers.

