SCOlib User Manual Version Version 1.0

## Installation

### Downloading

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

        http://www.cs.sandia.gov/~wehart/SGOPT

and earlier versions are available in the same directory.

The CVS repository for SGOPT can be accessed by executing

        cvs -d :ext:GEUutili@gaston.cs.sandia.gov:/usr/local/cvs/cvsroot checkout sgopt

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-s` can be used to encapsulate the access to the CVS repository. The `cvs-s` 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 SGOPT on UNIX systems is performed by the following steps:

1. Unpack the archive, unless you have already done that

           gunzip sgopt-$VERSION.tar.gz    # uncompress the archive
           tar xf sgopt-$VERSION.tar       # unpack it

2. Move into the `sgopt` directory and run the configure script.

           ./configure

   The `configure` script automates much of the setup activity associated with building large suites of programs like SGOPT 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 SGOPT 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. The following options are either commonly used or specific to SGOPT (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 DEBUGGING macro and sets the OPTIMIZATION macro to <flag> (code is compiled with -g by default).
   [--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 SGOPT 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. This is overridden by the --with-debugging flag.
   [--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. SGOPT 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 SGOPT relies on are located in the `sgopt/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
           SGOPT (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 SGOPT 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 sgopt/lib.

   Prior to making object files header files are linked into the directory `sgopt/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

SGOPT 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 `sgopt/src/vcpp`. This project defines a DLL that will be compiled for SGOPT, and it can be easily included in a user's workspace. The project file relies on the environmental variable `SGOPT', which is defined from the MS Windows Control Panel under `System/Environment`. This variable should be set to the path of the `sgopt` directory. Note: this project file is out of date.