Subsections

Overview

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:

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.7.0 ftp://tetra.mech.ubc.ca/pub/GRUMMP/GRUMMP-0.7.0.tar.gzis 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.7.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 are no VC++ project files for GRUMMP that are up-to-date enough to be useful. We would appreciate it if any user who succeeds in creating valid project files would

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.7.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.3 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.4 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-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.orgfor more information.
-with-CGM-path
This specifies the location of a recent version of the Argonne Common Geometry Module. If this option is omitted from the configure command, configure will automatically download and build CGM.
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. The build process does its best to supply the right linker magic so that the shared libraries are found automatically at runtime. If this fails (that is, if you get a message about a shared library not being available at runtime), add /home/me/GRUMMP-0.7.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: 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.6.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.

Carl Ollivier-Gooch 2017-07-20