Installation

Downloading

The UTILIB software can be downloaded either as a compressed tar file or directly from the UTILIB Concurrent Version System (CVS) repository. The latest release of UTILIB is available at 

    http://www.cs.sandia.gov/~wehart/UTILIB
and earlier versions are available in the same directory.

The CVS repository for UTILIB can be accessed by executing 

    cvs -d :ext:GEUutili@gaston.cs.sandia.gov:/usr/local/cvs/cvsroot checkout utilib
The password for this repository is 'anonymous'. The developer's password for this repository is restricted; please contact Bill Hart at wehart@sandia.gov to request the password to commit changes to this repository. If you are accessing this repository throught a firewall (e.g. Sandia's SRN firewall), or you expect to checkout updates frequently, then the script cvs-u can be used to encapsulate the access to the CVS repository. The cvs-u script can be downloaded at 
    ftp://ftp.cs.sandia.gov/pub/papers/wehart/src/cvs-shells.tar
Note that this script uses the ssh command, version 1.x.

Installation on Unix

Installation of UTILIB on UNIX systems is performed by the following steps:

  1. Unpack the archive, unless you have already done that 
        gunzip utilib-$VERSION.tar.gz    # uncompress the archive
    tar xf utilib-$VERSION.tar       # unpack it

  2. Move into the utilib directory and run the configure script. 
        ./configure

    The configure script automates much of the setup activity associated with building large suites of programs like UTILIB on various hardware platforms. This includes

    1. making symbolic links so that files used for configuration can be accessed from one location
    2. generating Makefiles so that objects, libraries, executables and other 'targets' can be created for specific and unique hardware platforms
    3. calling itself recursively so that sub-directories can also be configured
    By default, the configure script does not assume that UTILIB relies on any other software libraries. There are a number of configuration options that can be used to customize the installation. The full parameter list for the configure script is: 

       configure hosttype [--target=target] [--srcdir=dir] [--rm]
                      [--site=site] [--prefix=dir] [--exec-prefix=dir]
                      [--program-prefix=string] [--tmpdir=dir]
                      [--with-package[=yes/no]] [--without-package]
                      [--enable-feature[=yes/no]] [--disable-feature]
                      [--norecursion] [--nfp] [-s] [-v] [-V | --version]
                      [--help]

    Many of these options are not necessary since system information can be often acquired from your local machine. Refer to the Cygnus configure documentation for complete information (see utilib/doc/configure.ps). The following options are either commonly used or specific to UTILIB (examples of arguments are provided):

    [--with-compiler=<gcc,CC>] Sets up a specific compiler; The native compiler is the default.

    [--target=<solaris>] Optional flag to specify the target machine that you are cross-compiling for.

    [--site=<snl980>] Specifies the site-specific locations for MPI, etc.

    [--with-debugging] Turns on the OPTIMIZATION macro (code is compiled with the -g flag).

    [--with-mpi] Turns on the use of the MPI package.

    [--with-mpe] Turns on the use of the MPE package.

    [--with-swig] Enables the use of swig to wrap UTILIB for use with the Python scripting language.

    [--with-static] Enables the compilation of statically linked libraries (the default).

    [--with-insure] Enables the compilation with the insure++ debugging tool.

    [--with-shared] Enables the compilation of dynamically linked libraries, which can be shared.

    [--with-optimization=<level>] Sets the optimization level used when compiling the source files.

    [--with-ansi] Sets up the compiler to use ANSI standard constructs for C++. (the default)

    [--with-ansiheaders] Creates flags that force the use of ANSI standard C++ header conventions. (the dfault)

    The configure script creates Makefiles from Makefile.in template files, which outline the basic `targets' that need to get built. Variables that are package, site or hardware dependent are stored in individual `fragment' files. These `fragment' files are added to the custom created Makefiles when users and code developers (recursively) configure this repository with specific host, target, package and/or site parameters.

    Running configure takes a while, so be patient. Verbose output will always be displayed unless the user/developer wishes to silence it by specifying the parameter, `--silent'. If you wish to configure only one level/directory, remember to use the option `--norecursion'. All generated "config.status" files include this parameter as a default for easy makefile re-generation; after editing a Makefile.in file, you can construct the associate Makefile file by typing config.status.

    After the configure command is completed, three files will be generated in each configured directory (specified by the file, `configure.in').

    1. Makefile-${target}

      The suffix, ${target}, will depend on the target specified. Native builds have identical host and target values.

    2. Makefile

      This will be a symbolic link to the file mentioned above. A user or developer will simply type make and the last generated Makefile-${target} will then be referenced.

    3. config.status

      A `recording' of the configuration process (i.e., what commands were executed to generate the makefile). It can be used by the custom makefile to re-generate itself with a command such as this 

          make Makefile.
    Fragment files exist so that configure can support multi-platform environments. UTILIB can be configured for code development and execution on the following platforms : 

        SPARC-SUN-SOLARIS2.5.1   (Sun ULTRAsparc)
    MIPS-SGI-IRIX6.4         (SGI Octane)
    HPPA1.1-HP-HPUX9.05      (HP 9000/700 series)
    PENTIUM-INTEL-COUGAR     (Intel TFLOP supercomputer at SNL)
    i686-UNKNOWN-LINUX       (Red Hat 7.1)

    The fragment files for these platforms and for the packages that UTILIB relies on are located in the utilib/config directory. There are five types of files in this directory: 

        mf-<host>-<target>-<site>
    Automatically generated by the configure scripts.

    mh-<host>
    Fragments that define the utilities provided by the host (e.g. the 
    definition of MAKE.

    mp-<target>-<site>
    Fragments that define information for the packages that are used by 
    UTILIB (e.g. MPI).

    ms-<site>
    Fragments that define the site-specific general configuration 
    information. If this does not exist for a given site, then the 
    default ms-default fragment is used.

    mt-<target>
    Fragments needed to specfy how to compile code for a target 
    architecture (e.g. compiler name/location).

  3. Compile the program by running make. 

        make

    Note that the makefiles in UTILIB may not be portable to all make commands. However, they do work with the GNU gmake command. The latest file Makefile-${target} generated by configure will be referenced by this command. The target directory for the library is created for the particular target platform as a subdirectory of utilib/lib.

    Prior to making object files header files are linked into the directory utilib/include.

  4. Optional: Generate the html library documentation. 

        make html

    This requires the doxygen utility.

  5. Optional: Generate the postscript version of the user manual. 

        make ps

    This requires the doxygen, latex, and dvips.

  6. Optional: Generate the PDF version of the user manual. 

        make pdf

    This requires the doxygen, latex, dvips and ghostscript packages.

Installation on Windows

UTILIB was originally developed under UNIX, but it has been ported to Windows NT using Microsoft's Visual C++ (version 6.0). A MSVC++ project is provided in utilib/src/vcpp. This project defines a DLL that will be compiled for UTILIB, and it can be easily included in a user's workspace. The project file relies on the environmental variable `UTILIB', which is defined from the MS Windows Control Panel under System/Environment. This variable should be set to the path of the utilib directory. Note: this project file is out of date.