Basic Installation and Configuration ==================================== Installation of the SGOPT software library done from a distribution file (tape, etc.) or a checkout from the Concurrent Version System (CVS) repository. If you are accessing current files from the CVS repository, you need to use the "cvs-s" script, which can be downloaded from ftp://ftp.cs.sandia.gov/pub/papers/wehart/src/cvs-shells.tar. This script uses the CVS software utility, which you can download via anonymous ftp from a number of sites, for instance "prep.ai.mit.edu" in `pub/gnu'. This script also requires a developer or guest password, which you can request by emailing Bill Hart at wehart@sandia.gov. The SGOPT library can be checked out of the cvs repository by executing "cvs-s checkout sgopt". After the SGOPT software has been downloaded, it must be configured for building on specific hosts for specific target platforms. In short, a default setup can be executed by typing: ./confgure make This will configure the software for your machine and compile the SGOPT library. The "configure" script automates much of the setup activity associated with building large suites of programs (e.g. SGOPT) on various hardware platforms. Some of what "configure" does : a) makes symbolic links so that files used for configuration can be accessed from one location b) generates Makefiles so that objects, libraries, executables and other 'targets' can be created for specific and unique hardware platforms c) calls itself recursively so that sub-directories can also be configured 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] [-with-compiler=name] [--with-debugging] 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 sgopt/doc/configure.ps). The following options are either commonly used or specific to SGOPT (examples of arguments are provided): [--with-compiler=] Sets up a specific compiler; The native compiler is the default. [--target=] Optional flag to specify the target machine that you are cross-compiling for. [--site=] Specifies the site-specific locations for MPI, etc. [--with-debugging] Turns on the OPTIMIZATION macro (code is compiled with the -g flag). [--with-insure] Enables the use of the INSURE debugging utility. This can significantly slow down the code! [--with-mpi] Turns on the use of the MPI package. [--with-mpe] Turns on the use of the MPE package. [--with-optimization=<#>] Explicitly set the optimization level of the compiler. [--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-shared] Enables the compilation of dynamically linked libraries, which can be shared. [--with-ansi] Enables the use of new features in ANSI C++ that are not available on all compilers. (the default) [--with-ansiheaders] Enables the use of new include conventions for ANSI C++ that are not available on all compilers. (the default) 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, 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 your 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.7 (i.e., Sun ULTRAsparc) MIPS-SGI-IRIX6.4 (i.e., SGI Octane) HPPA1.1-HP-HPUX9.05 (i.e., HP 9000/700 series) PENTIUM-INTEL-COUGAR (i.e., Intel TFLOP supercomputer at SNLA) i686-UNKNOWN-LINUX (i.e., Red Hat Linux 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 5 types of files in this directory: mf--- Automatically generated by the configure scripts. mh- Fragments that define the utilities provided by the host (e.g. the definition of MAKE. mp-- Fragments that define information for the packages that are used by SGOPT (e.g. MPI). ms- 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- Fragments needed to specfy how to compile code for a target architecture (e.g. compiler name/location). Building the system =================== If you need to do unusual things to build the package, please determine if `configure' can be used to accomplish them. Notify us via e-mail by sending instructions to the address given in the `README' file so that a future release can incorporate your recommendations. Steps are outlined below for building/compiling the system after a successful configuration has taken place. 1. From the top-level directory, type the command, "make" to compile and build the system. The latest "Makefile-${target}" generated by "configure" will be referenced by this command. Note that the target directory for the library is created for the particular target platform as a subdirectory of sgopt/lib. 2. Prior to making object files, header files are linked into sgopt/include. 3. You can remove object files, libraries, and executables by typing "make clean". If you wish to re-configure your SGOPT source from scratch or re-generate all custom makefiles, type "make distclean". This will remove all symbolic links, custom makefiles, and "config.status" files. This will require a re-configure of the system and is usually done in preparation for updating source in the CVS repository or creating tape archives for distribution. 4. The simple command, "make", is all that is needed now to build the system for test and use. Similarly, you can force a recompilation of the library by typing "make install". Other targets exist in the makefile to support compilation by developers. Further, if the --with-swig option was specified for configure, then you can type "make python" to create a python executable that includes a SWIG-wrapped SGOPT library.