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@dix.mines.edu 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@dix.Mines.EDU 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.