Subsections

- Getting GRUMMP
- Building GRUMMP the easy way
- Building GRUMMP under Windows
- Configuring GRUMMP by hand
  - `configure` options
- Setting `LD_LIBRARY_PATH`
- If Your Machine Is Not Yet Officially Supported
- If Something Goes Wrong During Setup
  - Problems with `configure`
  - Problems with `make`
- Checking to be Sure Things Built Properly

# Getting Started

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`).1.2 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 3). 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.1.3 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

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 1.5.6 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.