[cig-commits] r4264 - long/3D/Gale/trunk

[walter at geodynamics.org]

Author: walter
Date: 2006-08-10 12:16:07 -0700 (Thu, 10 Aug 2006)
New Revision: 4264

Modified:
   long/3D/Gale/trunk/INSTALL
   long/3D/Gale/trunk/README
Log:
Fix INSTALL and pretty up README

Modified: long/3D/Gale/trunk/INSTALL
===================================================================
--- long/3D/Gale/trunk/INSTALL	2006-08-10 19:01:29 UTC (rev 4263)
+++ long/3D/Gale/trunk/INSTALL	2006-08-10 19:16:07 UTC (rev 4264)
@@ -1,11 +1,125 @@
- Installation Instructions
+These are generic installation instructions.  Gale has been tested on
+workstations running Mac OS X 10.4.6 (G4 and G5), Windows 2000 and XP
+SP2 (x86), RedHat Fedora Core 5 (x86), OpenSuse 10.0 (x86), Debian
+stable (x86 and AMD64), testing (x86) and unstable (x86).  If you are
+installing Gale on one of those systems, read through this file and
+then refer to the appropriate INSTALL file (e.g. INSTALL.MACOSX).
 
-1. Unpack the files.
+Gale has also been installed on a workstation running Gentoo (x86) and
+clusters running Redhat 7.2 (x86) and RedHat Enterpise Linux 3
+(EM64T).
 
-2. Run it from the command prompt:
 
-	./Gale-Linux simple-extension.xml   (Linux)
+Dependencies
+------------
 
-	./Gale-Mac simple-extension.xml   (Mac)
+In order to install Gale, you must have the headers and development
+libraries for
 
-	Gale-Win32 simple-extension.xml   (Windows)
+        - Petsc
+        - MPI
+        - libxml2
+
+You must also have python 2.2.1 or greater installed.  Generally, the
+most difficult part is installing Petsc.
+
+Configure
+---------
+
+The first step in installing Gale is running the script configure.py.
+This script examines your system, looking for dependencies.  It also
+determines where to install Gale.  By default, Gale will be installed
+in /usr/local.  You can override this with the --prefix option.  So to
+install it in /opt/gale, you would invoke configure.py as
+
+  configure.py --prefix=/opt/gale
+
+If you are lucky, configure.py will be able to find everything.  But many
+times, you will have to tell configure.py where different packages are.
+For example, suppose you installed Petsc in /opt/goodies/petsc.  Then
+you can tell configure.py where Petsc is with the --with-petsc-dir option
+
+  configure.py --prefix=/opt/gale --with-petsc-dir=/opt/goodies/petsc
+
+Petsc has a mechanism for letting multiple installations of Petsc
+coexist in a single directory (PETSC_ARCH).  If you have multiple
+installations, Gale will use the first one it finds. To override that
+guess, specify PETSC_ARCH with the option --with-petsc-arch
+
+  configure.py --prefix=/opt/gale --with-petsc-dir=/opt/goodies/petsc \
+    --with-petsc-arch=linux-gnu
+
+configure.py also checks the environment variables PETSC_DIR and
+PETSC_ARCH.
+
+Alternately, you can directly specify the library and include
+directories with the options --with-petsc-libdir and
+--with-petsc-include.
+
+For the other dependencies, configure.py accepts the options
+
+  --with-libxml2-include
+  --with-libxml2-libdir
+
+  --with-mpi-dir
+  --with-mpi-include
+  --with-mpi-lib
+  --with-mpirun
+  --with-mpi-compilers
+
+There are more options for advanced use.  To get a list of all
+available options, invoke configure.py with --help
+
+  configure.py --help
+
+configure.py saves a copy of everything it does in configure.log.
+When sending in bug reports, always include a copy of configure.log.
+
+
+Building
+--------
+
+Once you have configured successfully, run make
+
+  make
+
+This will build all of the libraries and header files that are needed
+for Gale.  Under the hood, make calls scons/scons.py.  So if you want
+to give additional options to scons.py, you can invoke it directly.
+For example, to run a parallel build because your machine has two
+processors
+
+  scons/scons.py -j 2
+
+
+Installing
+----------
+
+Finally, to install the code into its final resting place, run make install
+
+  make install
+
+This also uses scons.py under the hood.
+
+Testing
+-------
+
+Actually running Gale is a little complicated.  First of all, the
+executable is actually named Underworld.  Also, for various reasons,
+Gale will, at the moment, only run out of top directory of the source
+tree.  So you will need to make a symbolic link from wherever you
+installed Gale to the source tree.  For example
+
+  ln -s /usr/local/bin/Underworld
+
+There is a sample test input file: simple-extension.xml.  So to run
+this code, type
+
+  ./Underworld simple-extension.xml
+
+Gale is still in the early stages of development, so there are still
+many bugs.  This example should run about 29 time steps and then
+crash.  If you get different behavior (longer or shorter), please send
+a message to
+
+  cig-long at geodynamics.org

Modified: long/3D/Gale/trunk/README
===================================================================
--- long/3D/Gale/trunk/README	2006-08-10 19:01:29 UTC (rev 4263)
+++ long/3D/Gale/trunk/README	2006-08-10 19:16:07 UTC (rev 4264)
@@ -1,10 +1,11 @@
-We are pleased to announce the release of Gale 0.2.0.  This is a beta release, intended primarily for developers.
+We are pleased to announce the release of Gale 0.2.0.  This is a beta
+release, intended primarily for developers.
 
 See the file INSTALL for build and installation instructions.
 
 The latest release of Gale can always be found at
 
-   http://geodynamics.org:8080/cig/software/packages/gale/
+   http://geodynamics.org/cig/software/packages/gale/
 
 If you interested in following the main line of development, you can
 check it out using the Subversion command