The build and install process on UNIX platforms

NaSt3DGP is distributed as a standard UNIX tarball. First, you need to unpack the distribution. Depending on your version of tar, you can use one of the following commands to unpack the tarball to the current directory.

gzip -dc licenses/nast3dgp.tar.gz | tar xvf -

or

tar xvzf licenses/nast3dgp.tar.gz (if your version of tar support this).

Now change into the created subdirectory licenses/nast3dgp and issue the following command:

./configure [OPTIONS]

The command

./configure -help

will give you a complete list of available options with a short help message. The most important and NaSt3DGP-specific options are shown in table . Each option has a default value (also given in table ) which will be used if you do not specify the corresponding option. Table  lists other available configure options.

Table: Some useful options to configure.

-prefix=PREFIX	with this option you can control where NaSt3DGP will be installed when the make install command is issued. PREFIX is a directory. You need write-access to PREFIX when installing the program. The default value for PREFIX is /usr/local/.
-enable-mpi	with this option you control whether the parallel version of NaSt3DGP based on MPI will be built. You need a proper installation of an MPI implementation for this to work. The default value is always yes, if configure can detect an installation of MPI(configure tries to do this when running). If the configure script is unable to find a MPI installation, parallel build will be disabled. You can explicitly disable building the parallel version of NaSt3DGP by specifying -disable-mpi.
-enable-timer	with this option you control the output of timing information. If enabled, additional profiling information will be generated. The default value is no. (Remark: this switch affects only the parallel version, it is ignored when building the serial version.
-with-docdir=DIR	with this option you can specify a separate directory for installation of the documentation. The default value for DIR is [PREFIX/share/doc/licenses/nast3dgp].

Table: Some more options to configure.

-h, -help	display this help and exit
-help=short	display options specific to this package
-help=recursive	display the short help of all the included packages
-V, -version	display version information and exit
-q, -quiet, -silent	do not print `checking...' messages
-cache-file=FILE	cache test results in FILE [disabled]
-C, -config-cache	alias for `-cache-file=config.cache'
-n, -no-create	do not create output files
-srcdir=DIR	find the sources in DIR [configure dir or `..']
-prefix=PREFIX	install architecture-independent files in PREFIX [/usr/local]
-exec-prefix=EPREFIX	install architecture-dependent files in EPREFIX [PREFIX]
-bindir=DIR	user executables [EPREFIX/bin]
-sbindir=DIR	system admin executables [EPREFIX/sbin]
-libexecdir=DIR	program executables [EPREFIX/libexec]
-datadir=DIR	read-only architecture-independent data [PREFIX/share]
-sysconfdir=DIR	read-only single-machine data [PREFIX/etc]
-sharedstatedir=DIR	modifiable architecture-independent data [PREFIX/com]
-localstatedir=DIR	modifiable single-machine data [PREFIX/var]
-libdir=DIR	object code libraries [EPREFIX/lib]
-includedir=DIR	C header files [PREFIX/include]
-oldincludedir=DIR	C header files for non-gcc [/usr/include]
-infodir=DIR	info documentation [PREFIX/info]
-mandir=DIR	man documentation [PREFIX/man]
-program-prefix=PREFIX	prepend PREFIX to installed program names
-program-suffix=SUFFIX	append SUFFIX to installed program names
-program-transform-name=PROGRAM	run sed PROGRAM on installed program names

Further finetuning of the build process can be achieved by supplying additional environment variables on the configure command-line, i.e.

./configure [OPTIONS] VAR=VALUE

See table  for a list of used environment variables.

Perhaps the most important variable is CXXFLAGS. You can use it for instance to control the level of optimization(default optimization level depends on the compiler detected by configure, for GNU compilers it is usually -O2). For example, on a Linux system running on a pentium class or higher processor, you could use the following command:

./configure [OPTIONS] CXXFLAGS='-Wall -ansi -O3 -mcpu=pentiumpro -ffast-math -funroll-loops'

By default, configure picks the first compiler it detects on the hosts system. With the variable CXX you can explicitly specify the C++-compiler which should be used during the build process.

In order to build a parallel version of NaSt3DGP (see option -enable-mpi in table ) you need a proper installation of an MPI implementation. You can download the free MPI implementation MPICH from the Computer Science Division of the Argonne National Laboratory http://www-unix.mcs.anl.gov/mpi/mpich/.

By specifying the variables MPICXX and MPILIBS you can build a parallel version of NaSt3DGP even if the configure script could not detect an installation of MPI in one of the standard locations. With some versions of MPI you can use the variable MPICXX to force the usage fo a specific C++-Compiler, for example

./configure [YOUROPTIONS] MPICXX='mpiCC -CC=/path/to/your/compiler/bin/g++'

For driver-scripts which do not support the -CC option (usually the driver-scripts of SCore don't) you might use the following workaround: just make sure that the compiler you want to use is the first to appear in your path, that is the one some driver-script use (e.g. SCore version 5 does).

Table: Additional environment variables for configure.

CXX	specify a C++ compiler other than the one detected by configure
CXXFLAGS	flags for the default compiler or the one specified with CXX
LDFLAGS	linker flags, e.g. -L $\langle$lib dir$\rangle$ if you have libraries in a nonstandard directory $\langle$lib dir$\rangle$
CPPFLAGS	C/C++ preprocessor flags, e.g. -I $\langle$include dir$\rangle$ if you have headers in a nonstandard directory $\langle$include dir$\rangle$
CC	C compiler command
CFLAGS	C compiler flags
CXXCPP	C++ preprocessor
MPICXX	MPI C++ compiler command
MPILIBS	necessary libraries to link MPI C code

After a successfull run of configure, just type

make

or

make -j 2

if building on a 2-processor machine. After the build process has successfully finished, type

make install

to install NaSt3DGP into PREFIX, where PREFIX is the directory you specified with the -prefix option when configuring. After installation you will find the following subdirectories and files located under PREFIX:

• in PREFIX/bin you will find the binaries navsetup, vrml2nav, navcalc and also navcalcmpi if the parallel version was built. navsetup is a multi-purpose interface tool for generating input files for navcalc and generating output for visualization. A detailed description is given in chapter . The binaries navcalc and navcalcmpi are used to perform the actual numerical calculations. The program vrml2nav is used to convert geometry data in vrml 1.0 format into the nav-format readable by navsetup.
• in PREFIX/share/doc/licenses/nast3dgp you will find the documentation in Adobe PDF format.
• in PREFIX/share/licenses/nast3dgp/examples you will find several subdirectories containing example input files for navsetup.
• in PREFIX/share/licenses/nast3dgp/tools/GridGen you will find GridGen, a tool to generate smoothly distributed grid lines. More information on this tool is given in section . Please note that this tool is included only for convenience, it is not fully supported. GridGen is distributed in Fortran77 source code only and will not be generated automatically, you need an F77-compiler to build the binary.
• in PREFIX/share/licenses/nast3dgp/tools/matlab you will find Matlab-functions to read NaSt3DGP-generated data-files into Matlab and to write files in the same format