README_TO_INSTALL  the CWP/SU  Free Software Release 43    20 Dec 2011 

-----------------------------------------------------------------
Legal stuff 
-----------------------------------------------------------------
Warranty Disclaimer:
THIS SOFTWARE IS PROVIDED BY THE COLORADO SCHOOL OF MINES AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COLORADO SCHOOL OF MINES OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.

****Please read the file LEGAL_STATEMENT for a full description of 
the user license and legal restrictions for this software package.*


This file begins with a brief description of the installation procedure
followed by a more detailed discussion of each step.

### Brief description of the installation procedure:
### Be sure to read the more detailed list that follows this one.

------------------------------------------------------------------
The installation procedure at a glance
------------------------------------------------------------------

Installing the codes consists of 7 basic steps:
1) read the README's before unbundling cwp_su_all_xx_tar.gz
2) don't install as 'root' (the superuser) (It is possible to damage
   a system's file structure if the install is not done properly.)

3) begin with the gzipped tarfile cwp_su_all_xx.tgz  or
   located in some convenient directory that you have
   read and write permission in that we will call:
   /your/root/path

4) set the CWPROOT environment variable to  CWPROOT to /your/root/path
   log out and log back in
   
5) put /your/root/path/bin on your path or PATH
   this procedure is different depending on which of
   the below working shells you are using:
   /bin/csh  /bin/tcsh  /bin/sh  /bin/bash  /bin/ksh

6) uncompress and untar the compressed tarfile via:
   zcat cwp_su_all_xx.tgz | tar -xvf -
   or:
   gunzip  cwp_su_all_xx.tgz 
   tar -xvf cwp_su_all_xx.tar

   The code will appear as the single directory  /your/root/path/src

7) compile codes via:
        cd /your/root/path/src
   1) look in the directory /your/root/path/src/configs
      for a file named Makefile.config.ARCH where ARCH matches
      your system architecture

      cd $CWPROOT/src
      cp configs/Makefile.config.ARCH $CWPROOT/src/Makefile.config

      You may have to edit Makefile.config

   2) type: 
	   these are essential:
           make install   (to install the basic set of codes)
           make xtinstall (to install the X-toolkit applications)
          
           the rest are nonessential:
           make xminstall (to install the Motif application)(nonessential)
           make finstall (to install the Fortran codes)
           make mglinstall (to install the Mesa/ Open GL items)
           make utils     (to install libcwputils) (nonessential) 

or if remaking:
      type: make remake   (to remake the basic set of codes)
           make xtremake (to remake the X-toolkit applications)
           make finstall (to install the Fortran codes)
           make mglremake (to install the Mesa/ Open GL items)
           make uremake  (to remake libcwputils.a)(nonessential)
           make xmremake (to remake the Motif-based applications)


If the codes fail to compile the first time through, it may
be that you have made a mistake in one of the 6 previous procedures,
or it may be that your system or setup are different from what
we expect. In this event, you
may simply type "make" in the directory where you were modifying
code. If code appears to have been missed, you may need to
use the "remaking" options. 

A screen dump of a successfull install of the current version
of the codes on an Fedora Core 5 Linux platform may be found
in the file: "install.successful"  so you can see what it is
supposed to look like.

----------------------------------------------------------
Detailed description of the installation procedure:
----------------------------------------------------------

1) Text files that you need to read:
   Installation_Instructions -- this file
   LEGAL_STATEMENT --- copyright, license, disclaimer, and acknowlegements
   README_TO_INSTALL_ --- how to begin using the codes
   Portability/       --- portability information for various platforms
             ./README_APOLLO            --- HP Apollo instructions
             ./README_CONVEX            --- Convex instructions
             ./README_C++               --- Experimental C++ instructions
             ./README_CRAY              --- Cray instructions
             ./README_CWPUTILS          --- CWP utility instructions
             ./README_DEC               --- DEC instructions
             ./README_DEC_ALPHA         --- DEC Alpha instructions
             ./README_FREE_BSD          --- Free BSD instructions
             ./README_FREE_SOFTWARE_FOUNDATION -- Free Soft. Found. info
             ./README_GCC               --- GNU CC compiler instructions
             ./README_GNU_MAKE          --- GNU make instructions
             ./README_HP                --- HP make instructions
             ./README_LESSTIF           --- Lesstif info
             ./README_LINUX             --- Linux instructions
             ./README_LITTLE_ENDIAN     --- little endian (low byte)
             ./README_MESA_OPEN_GL      --- Mesa/OpenGL  instructions
             ./README_RS6000            --- IBM RS6000 instructions
             ./README_SEG2SEGY          --- converting SEG2 to SEGY
             ./README_SILICON_GRAPHICS  --- SGI instructions
             ./README_SOLARIS           --- for Solaris 2.xx and newer
             ./README_SUN               --- SUN OS 4.xx and older
             ./README_THIRD_PARTY       --- Additional third party codes
             ./README_X                 --- X-windows tips
             ./README_XDR               --- XDR info for 64 bit machines
              
   Note: none of these files is absolutely comprehensive. We rely on
   user supplied information for porting the codes to other platforms
   (such as HP, DEC, Silicon Graphics, Convex, Cray, etc.),
   so your comments are important in helping us keep the installation
   process as simple as possible.

2) We advise that you do *not* try to install the CWP/SU codes as "root"
   as a safety feature, though precautions have been taken to keep
   the codes from installing in "root" areas. Install the codes as a
   "regular user", not the superuser.

   At least 2 users have reported that they have corrupted their file
   systems, while installing under Linux because they ignored this
   warning. So, we warned you.

3) Begin with the gzipped tarfile  cwp_su_all_xx.tgz  
   file in a convenient location
   that we will call: /your/root/path

   A) Create a directory with some path that we will call 
       "/your/root/path".
      We don't mean that the directory path be literally called
      "/your/root/path". It can be any convenient directory on your system.
      You may need the system administrator on your site to set up such
      a directory if it is not in subdirectory owned by you.

      /your/root/path should be chmoded to be writable by the "regular" 
      user who is performing the install.
 
      Finding a good location for the codes to reside on your system is
      important. When the codes are uncompressed, untarred, and compiled 
      they take up about 20 megabytes. The demos generate files that may
      be considerably larger, so the more space you have available, the
      better.
 
   B) About /your/root/path:
 
      The Makefiles throughout the CWP codes operate on the assumption
      that the directories containing the include files, libraries, and
      executable codes will be installed under a central root path
      of the form of  /your/root/path. When you unbundle 
      the gzipped tarfile  cwp_su_all_xx.tgz 
      in /your/root/path, the directory /your/root/path/src will appear, 
      containing all of the source code.
 
      Many of the shell scripts used in the package depend on accessing
      the source code, so sticking to this convention is necessary for
      correct operation of the package.
 
      When you compile the codes:
      the "libraries" will be installed in /your/root/path/lib, 
      the "include files" will be installed in /your/root/path/include,
      and the "executable files" will be installed in /your/root/path/bin.
 
      You may choose  /your/root/path to be anything that is 
      most convenient for you and compatible for your system, 
      provided that /your/root/path exists and is chmoded to be 
      writable by the user installing the CWP codes.
      (Again, for safety, don't try to install the codes as "root".)
 
      Examples of /your/root/path:

    		/usr/local/cwp
    		/Users/harry/cwp
    		/u/user/bob/scratch/codes
    		/scratch/bob/csm
    
      However, if for some reason you cannot have the CWP source codes
      immediately under /your/root/path, then it is still possible
      install the codes successfully.

      NOTE: If for some reason the CWP source code cannot be 
            placed immediately under /your/root/path on your system,

            For example:

            if the source code is in:  /Users/bob/stuff/cwp/src 
            but the user wants to install the stuff under another path
            for example:   /system/local 
        Then the user would define: CWPROOT to be /system/local
 
        To make the source code appear to be in /system/local/src,
        a symbolic link pointing from /Users/bob/stuff/cwp/src to
        /system/local/src may be made via the command:
 
                    ln -s /Users/bob/stuff/src /system/local/src

 
   Warning: If you are unfamiliar with symbolic links, please consult
            your local UNIX guru.

    
4) Setting the necessary environment variable  CWPROOT.
    
   All of the Makefiles imbedded in the CWP codes depend on there being
   defined in the users' working shell environment a variable called
   "CWPROOT" that is set to the value of /your/root/path. This permits
   the Makefiles to install the libraries in /your/root/path/lib,
   the include files in /your/root/path/include, and the executables in
   /your/root/path/bin without forcing the user to manually edit all
   (60+) Makefiles.
   
   C Shell or TCSH shell:
    For a user of C Shell (csh) (or tcsh) the CWPROOT environment 
    variable is set by adding the line
 
   setenv CWPROOT /your/root/path
 
   in his or her  .cshrc file and relogging.
 
   Korn Shell, Born Shell, and BASH
 	For a user of Korn Shell (csh) (or Born Shell (sh)
         or Bourne Again Shell (bash) ) 
   the CWPROOT environment variable is set by adding the line
 
   export CWPROOT=/your/root/path
 
   in his or her  .profile, .bash_rc, or .bash_profile file 
   and relogging. These files are in your home directory and can
   only be seen by typing:    ls -la 

   To see if you have done this correctly, type:
   echo $CWPROOT
   The value of /your/root/path should be returned.
 
5) Put /your/root/path/bin in your working shell path. This must be
   done so your working shell can find the executables.

   In C shell (csh or tcsh) this is done by modifying the set path line:
   set path=( /your/root/path/bin ~/bin /usr/local/bin /bin  ....)
   (You just add /your/root/path/bin to the list of stuff that is already
    there.)

   in the user's  .cshrc file. 
   (C shell users will need to remember to relog to get these changes
    to take effect and 'rehash' after compiling the codes, so that your
    working shell will be able to find the executables.)

   In Korn (ksh), Bourne (sh), or Bourne Again (bash)  Shells, modify
   the line:

   export PATH=:/your/root/path/bin:$HOME/bin:/bin:/usr/bin: ...etc...

   (You just add /your/root/path/bin to the list of other stuff that is
    already there.)
   in the user's  .profile file. You will need to relog.
    Another common form is:

    PATH=$PATH:/your/root/path/bin:.
    export PATH
   
   If you don't have a line like this in your .profile, then you may need
   to ask a Unix guru for help. If you don't have such a person at
   your site, then you may need to see the files in /etc/ which set up
   the general profile for all sh, bash, or ksh on your system.
 	   
6) Untarring and uncompressing the compressed tarfiles. 
 
    IMPORTANT: Begin the installation by extracting the codes from
    the gzipped tarfile cwp_su_all_xx.tgz /your/root/path
    (see the discussion in 3) of this file for more info
    about /your/root/path). (The "xx" is the current Release number.)
 
    You may uncompress and untar the codes manually via the command:
 
    zcat cwp_su_all_xx_tar.gz | tar -xvf -
    
    Another common way to proceed is:
    gunzip  cwp_su_all_xx.tgz

    and then:
    tar -xvf cwp_su_all_xx.tar
   
    Don't remove the cwp_su_all_xx.tgz in event you have a problem
    that requires that you start over from the beginning.

    If you are installing on a Linux system and can't seem to find
    zcat, then you have not installed all of the operating system.
 
7) Compiling the codes.
 	
    One master Makefile is provided to compile the codes.
    Note, this file will refuse to compile the codes if the
    CWPROOT environment variable is not set.
    See step 2) of these instructions for information about the CWPROOT
    environment variable. Read this file carefully before proceeding.

    The file  "Makefile.config" is provided to permit the user to make
    global changes to the "make" proceedure, without having to edit
    any of the Makefiles. Read this file and make whatever changes are
    necessary for compatibility with your system.
 
You will then compile the codes by typing:

	make install   ----  to install the cwp, plot, and su packages
	make xtinstall ----  to install the X windows codes
	make xminstall ----  to install the Motif based codes

If you have to recompile along the way 
	type:

	make remake    ---- to recompile the cwp, plot, and su packages
	make xtinstall ---- to recompile the X-Toolkit based codes
	make xminstall ---- to recompile the Motif based codes


If you have problems with the installation, there are archives of 
user comments on the web. Simply doing a google search on your specific
error message may reveal the answer.

One common problem is that a user may not have all of the 
developers' materials for your operating system installed. This 
usually is revealed by complaints about a missing include file 
at the system level. Most operating systems are set up to have
separate installations for "non-expert" and "expert" users
(or developers). 

You may have to change the include and/or link paths in the X-windows 
directories.  Therefore, it is a good idea to do each of these makes 
separately, rather than trying to do them all in one shot via a
command like:

Normally you *Don't* do this
==>> % make install ; make xtinstall ; make xminstall  
unless you have the system completely set up.

----------------------------------------------------------------
Developer Tools. !!!!!! Experimental ---- use at your own risk!!!!!
----------------------------------------------------------------

Experimental developer tools are provided in
$CWPROOT/src/developer_tools

cp $CWPROOT/src/developer_tools/*  $CWPROOT/src/

the scripts Configure, Build, and Install are the beginnings of an
autoconfiguration and installation procedure. In theory you
should be able to just type
./Configure
and then 
./Build

To configure the Makefile.config, and compile the codes.
the script
./Install 

allows users to install the executables under a directory path
$CWPROOT/ARCH/bin

where ARCH is the architecture of the system they are installing
under. This feature is useful if the same source code is being
installe on different platforms. 

The tool Fatsafe is provided to allow developers to check to
see if their directory tree is safe to install on VFAT (FAT32)
filesystems.


Some of the directories contain Portability subdirectories. There
may be variations on the codes in there that you can implement to get the
codes to compile. We have made most of the portability directories
unnecessary via the magic of compile time flags.

Questions regarding the installation and portability should be 
addressed to: john.19071969@gmail.com

You may also join the "seisunix" discussion group by clicking on the link
to this site on the web page:  http://www.cwp.mines.edu/cwpcodes
 
John Stockwell	 | john.19071969@gmail.com
Center for Wave Phenomena (The Home of Seismic Un*x)
Colorado School of Mines
Golden, CO 80401 | http://www.cwp.mines.edu/cwpcodes
voice: (303) 273-3049  |    fax: (303) 273-3478.
