Skip navigation links
(Wind-US Documentation Home Page) (Wind-US User's Guide) (GMAN User's Guide) (MADCAP User's Guide) (CFPOST User's Guide) (Wind-US Utilities) (Common File User's Guide) (Wind-US Installation Guide) (Wind-US Developer's Reference) (Guidelines Documents) (Support)

(Overview) (Obtaining Wind-US and the Tools) (Installing the Build Distributions) (Installing the Build Distributions on NAS) (Porting Wind-US to a New UNIX Platform)

Installing the Build Distributions

Wind-US and the tools are designed to be compiled in a build (or development) directory and then the final executables installed into an application directory. This allows one to install multiple versions of Wind-US into a single application directory that uses shared run-time scripts. The user can select which version to use at run-time. The following sections describe the steps necessary to install the build distributions in this manner.

Building Wind-US

Makefiles are distributed with the Wind-US build distribution for a variety of platform, operating system, and CPU combinations, including:

If you need to build the code for a platform not listed above, you will need to first create the appropriate makefiles, using the existing ones as a starting point. See the section Porting Wind-US to a New UNIX Platform for further information.

Assuming the appropriate makefiles exist, the recommended procedure to build and install Wind-US from source is as follows. Please re-read each step completely before executing any commands that are described.

  1. Create an appropriate top-level directory.

       mkdir -p $HOME/WINDUS
       cd       $HOME/WINDUS
    

    This will ultimately contain the build/development source (wind-dev) and application executable (wind) subdirectories.

    If an existing top-level Wind-US installation directory is to be used, the existing wind-dev subdirectory should be renamed so that it is not overwritten. Any makefiles you may have modified within this directory may be of use in constructing makefiles for the new installation.

    When installing multiple versions into a shared installation directory, one should start with the oldest version and work towards the newest. This way the most current run scripts will be made available. Installing an older version into an existing directory might install older run scripts that do not support more recent code options.

  2. Put the gzip'ed tar file containing the Wind-US build distribution into this directory. You should now have a file of the form:

       dist.windus.x.xxx.tgz
    
  3. Unpack the Wind-US build distribution by doing:

       gunzip -c filename | tar xvf -
    

    where filename is the file name, including the .tgz extension. This creates a directory named wind-dev containing the Wind-US source code. There will also be two scripts to assist with the installation: Install.appl and Install.tools.

    If you also plan to install the tools, you should follow those instructions in parallel with these. In particular, it is important to unpack the tools build bundle before proceeding with any changes to the makefiles. Otherwise those changes could be overwritten when you do eventually unpack the tools.

  4. Use the installation script to create the application directory and copy some necessary scripts. Responses to the interactive prompts are shown in italic font.

       ./Install.appl
    
       Under what parent directory should Wind-US be installed?
         (Default is current directory):
       Hit enter to accept the default directory.
    
       Run scripts will be installed in $HOME/WINDUS/wind/bin
       Is this OK? (y/n [y])
       Answer: y
    
       Copying files to $HOME/WINDUS/wind
       Modifying cfd.login and cfd.profile
    
       Wind-US scripts have been copied to the installation directory. 
       To finish the installation ...
    
       csh/tcsh users: add the following line to your .login file
          source $HOME/WINDUS/wind/bin/cfd.login
    
       sh/bash/ksh users: add the following line to your .profile file
          . $HOME/WINDUS/wind/bin/cfd.profile
    
  5. Update the login scripts

    Follow the instructions described by the script output to update your login scripts. At the same time, define the environment variable WIND_DEV as the location of the directory containing the top-level Makefile. This should be the full path to the wind-dev directory.

    Typically, csh and tcsh users must edit their $HOME/.login file and add the following two lines:

       setenv WIND_DEV "path_name/wind-dev"
       source path_name/wind/bin/cfd.login
    

    where again path_name is the full path name of the directory used in step 1. Similarly, bash, ksh, and sh users must edit their $HOME/.profile file and add the following two lines:

       WIND_DEV="path_name/wind-dev"; export WIND_DEV
       . path_name/wind/bin/cfd.profile
    

    This causes the contents of the cfd.login (or cfd.profile) file to be executed automatically at login time to set up the environment variables CFDROOT, SYSTEM, and SYSTEM_CPU, that are required for installing and running Wind-US, and to modify your PATH to include the location of the Wind-US executable.

  6. At this point, log out and log back in to execute your .login or .profile file (depending on your login shell). Alternatively, in your home directory execute (for csh and tcsh users)

       source .login
    

    or (for sh and ksh users)

       . .profile
    
  7. Check to see if the environment variables have been set to appropriate values, by doing

       printenv WIND_DEV
       printenv CFDROOT
       printenv SYSTEM
       printenv SYSTEM_CPU
    

    WIND_DEV was defined in step 5. CFDROOT should have a value of path_name/wind where path_name is the full path name of the directory used in step 1. This represents the root location that contains the Wind-US executable(s) and scripts. SYSTEM and SYSTEM_CPU should describe the operating system and cpu type. If all are correctly set, skip the next step.

  8. If CFDROOT is not set properly, you will need to manually edit the Wind-US login script. Denoting path_name as the full path name (starting with a "/") of the directory used in step 1, users of the csh or tcsh shell should edit the file path_name/wind-dev/bin/cfd.login to modify the definition of CFDROOT as follows:

       if (! "$?CFDROOT") then
       #=BEGROOT=
         setenv CFDROOT "path_name/wind"
       #=ENDROOT=
       endif
    

    Similarly, bash, ksh, or sh users would edit the file path_name/wind-dev/bin/cfd.profile to modify the definition of CFDROOT to:

       if [ ! "$CFDROOT" ] ; then
       #=BEGROOT=
         CFDROOT="path_name/wind" 
       #=ENDROOT=
         export CFDROOT
       fi
    

    Return to step 6 to have this change take effect.

  9. Now that the environment variables are set properly, move into the WIND_DEV directory.

       cd $WIND_DEV
    
  10. Configure the makefiles.

    The default values in the configuration files should be sufficient to produce an executable on most well-configured systems (assuming that compilers are installed). The primary exception to this is Linux, which does not have a "default" Fortran 90/95 compiler. Another potential problem is the location of the MPI libraries, which needs to be specified if you wish to use MPI for parallel runs. To be safe, review the contents of the following files or parts of files, where SYSTEM and SYSTEM_CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, paying special attention to the items noted below.

    When modifying files it is always a good idea to save a copy of the original (i.e., as *.bak), and for new files to create an empty *.bak file. This makes it easy to identify which files you have changed, and you can use a visual difference program to compare those changes against the original.

  11. Compile the Wind-US source.

    From the WIND_DEV directory, run make to create all the required libraries and executables for running Wind-US. The output from the compilation process is very lengthy. To capture the output from make in the file make.log for later examination if something goes wrong, in addition to displaying it at the terminal, csh and tcsh users should do

       make opt |& tee make.log
    

    and sh and ksh users should do

       make opt 2>&1 | tee make.log
    

    If the compilation is successfull, the Wind-US executable should be present in the directory $WIND_DEV/SYSTEM/SYSTEM_CPU/bin.

  12. To install the compiled Wind-US and PVM executables into the application directory, use the following commands:

       make install
       make install_scripts
       make copy_pvm
    

    The first two commands copy the Wind-US executable to $CFDROOT/SYSTEM/CPU/bin and the scripts to $CFDROOT/bin. The third copies the PVM executables and libraries to $CFDROOT/pvm/SYSTEM/CPU, some PVM include files to $CFDROOT/pvm/include, and PVM scripts to $CFDROOT/pvm/lib. The parameters SYSTEM and CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, respectively.

    Note that the Wind-US executables are named by major revision number (i.e., Wind-US4.exe). However, in some cases, such as before and after a bug fix, it is useful to retain minor revisions. To do so, before issuing the install commands listed above, you should rename the existing executable in the application directory ($CFDROOT/SYSTEM/SYSTEM_CPU/bin) to include the minor revision number (i.e., Wind-US4.111.exe). The windver script can be used to print the version number for a particular executable.

  13. It would be best to log out and log back in before running Wind-US. This executes the shell start-up scripts, modifying the PATH environment variable to include the newly-created location for the Wind-US executable.

Building the Tools

The tools build distribution is designed to be a completely independent package, so that the tools can be built without requiring any additional files from Wind-US. Thus, one could have separate directory trees for the Wind-US build distribution and tools build distributions. This would lead to a great deal of duplication, however. Therefore, the build distributions are designed to overlay one another. The following instructions assume that all the tools are being built in the same directory tree. Please re-read each step completely before executing any commands that are described.

  1. Create an appropriate top-level directory.

       mkdir -p $HOME/WINDUS
       cd       $HOME/WINDUS
    

    This will ultimately contain the build/development source (wind-dev), more specifically (wind-dev/tools-dev), and application executable (wind) subdirectories.

    An existing top-level Wind-US directory is often used for this purpose, since it reduces the amount of extra disk space and configuration necessary. In this case, you will want to use the directory above wind-dev. See step 11 in the procedure for building Wind-US.

  2. Install lua version 4.01 if it is not already available on your system. Note that due to changes in the API, newer versions of lua will not work with the Wind-US tools. These instructions assume that lua will be installed under the top-level directory of step 1. However, it could be installed in its own stand-alone location.

    Download the source code from http://www.lua.org/ftp/lua-4.0.1.tar.gz external link and save as:

       lua.4.0.1.tar.gz
    

    Unpack the source files.

       gunzip -c lua.4.0.1.tar.gz | tar xvf -
    

    This will extract the lua.4.0.1 directory. To compile lua,

       cd lua.4.0.1
       make
    

    This should create the following files:

       $HOME/WINDUS/lua-4.0.1/bin/lua
       $HOME/WINDUS/lua-4.0.1/bin/luac
       $HOME/WINDUS/lua-4.0.1/lib/liblua.a
       $HOME/WINDUS/lua-4.0.1/lib/liblualib.a
    
  3. Install the CGNS library if it is not already available on your system. Once again, these instructions assume that it will be installed under the top-level directory of step 1. However, it could be installed in its own stand-alone location.

    Download cgnslib (2.5.5) from https://cgns.github.io/download.html external link and save as:

       cgnslib.2.5.5.tar.gz
    

    Newer versions of cgnslib may also work. Unpack the source files.

    gunzip -c cgnslib.2.5.5.tar.gz | tar xvf -
    

    This will extract the cgns_2.5 directory. Compile the CGNS library with commands similar to the following. You may need to adjust the settings, depending on your system.

       cd $HOME/WINDUS/cgnslib_2.5
       ./configure --prefix=$HOME/WINDUS/cgnslib_2.5 --with-system=LINUX64 --enable-64bit
       make SYSTEM=LINUX64
       mkdir include
       mkdir lib
       make install
    

    This should create the following files:

       $HOME/WINDUS/cgnslib_2.5/include/cgnslib.h
       $HOME/WINDUS/cgnslib_2.5/include/cgnslib_f.h
       $HOME/WINDUS/cgnslib_2.5/include/cgnswin_f.h
       $HOME/WINDUS/cgnslib_2.5/lib/libcgns.a
    
  4. Put the gzip'ed tar file containing the tools build distribution into the top-level directory used in step 1. You should now have a file of the form:

       dist.alltools.tgz
    
  5. Unpack the tools build distribution by doing:

       gunzip -c dist.alltools.tgz | tar xvf -
    

    This creates a directory named wind-dev containing the source code. The source code for individual tools will be located in subdirectories of wind-dev/tools-dev. There will also be two scripts to assist with the installation: Install.appl and Install.tools.

    If you also plan to install Wind-US, you should follow those instructions in parallel with these. In particular, it is important to unpack all of the build bundles before proceeding with any changes to the makefiles. Otherwise those changes could be overwritten when unpacking another bundle.

  6. Follow steps 4-8 in the procedure for building Wind-US and verify that the WIND_DEV, CFDROOT, SYSTEM, and SYSTEM environment variables are correctly defined.

  7. Use the installation script to create the application directory and copy some necessary scripts. Responses to the interactive prompts are shown in italic font.

       ./Install.tools
    
       Under what parent directory should the tools be installed?
         (Default is current directory):
       Hit enter to accept the default directory.
    
       Run scripts will be installed in $HOME/WINDUS/tools/bin
       Is this OK? (y/n [y])
       Answer: y
    
       Copying files to $HOME/WINDUS/tools
       Modifying tools.login and tools.profile
    
       Wind-US scripts have been copied to the installation directory. 
       To finish the installation ...
    
       csh/tcsh users: add the following line to your .login file
          source $HOME/WINDUS/tools/bin/tools.login
    
       sh/bash/ksh users: add the following line to your .profile file
          . $HOME/WINDUS/tools/bin/tools.profile
    
  8. Update the login scripts.

    Follow the instructions described by the script output to update your login scripts. Typically, csh and tcsh users must edit their $HOME/.login file and add the following line:

       source path_name/tools/bin/tools.login
    

    where again path_name is the full path name of the directory used in step 1. Similarly, bash, ksh, and sh users must edit their $HOME/.profile file and add the following line:

       . path_name/tools/bin/tools.profile
    

    This causes the contents of the tools.login (or tools.profile) file to be executed automatically at login time to set up the TOOLSROOT environment variable that is required for installing and running the tools, and to modify your PATH to include the location of the tools executables.

  9. At this point, log out and log back in to execute your .login or .profile file (depending on your login shell). Alternatively, in your home directory execute (for csh and tcsh users)

       source .login
    

    or (for sh and ksh users)

       . .profile
    
  10. Verify that the TOOLSROOT environment variable is properly set, by doing:

       printenv TOOLSROOT
    

    It should have a value of path_name/tools where path_name is the full path name of the directory used in step 1. If it is, skip the next step.

  11. If TOOLSROOT is not set properly, you may need to manually edit the tools login script. Denoting path_name as the full path name (starting with a "/") of the directory used in step 1, users of the csh or tcsh shell should edit the file path_name/tools/bin/tools.login to modify the definition of TOOLSROOT as follows:

       #=BEGROOT=
       setenv TOOLSROOT "path_name/tools"
       #=ENDROOT=
    

    Similarly, bash, ksh, or sh users would edit the file path_name/tools/bin/tools.profile to modify the definition of TOOLSROOT to:

       #=BEGROOT=
       TOOLSROOT="path_name/tools"
       #=ENDROOT=
       export TOOLSROOT
    

    Return to step 9 to have this change take effect.

  12. Now that the environment variables are set properly, move into the WIND_DEV directory.

       cd $WIND_DEV
    
  13. Configure the makefiles.

    Most systems other than Linux should be able to use the default values in the configuration files without problem. On Linux systems, it is likely that the definitions related to the Fortran and C compilers will have to be changed. To be safe, check the following files to be sure they contain information that is appropriate for your system. (See the notes for step 10 in the procedure for building Wind-US).

  14. Compile the tools source.

    In the WIND_DEV directory, run make to create all the required libraries and executables for all the tools for which you have installed source. To capture the output from make in the file make_tools.log for later examination if something goes wrong, in addition to displaying it at the terminal, csh and tcsh users should do

       make all_tools |& tee make_tools.log
    

    and sh and ksh users should do

       make all_tools 2>&1 | tee make_tools.log
    

    You can also compile tools individually, by doing

       make tool_name
    

    where tool_name is the name of the tool. Note that the names to be used for GMAN, CFPOST, and MADCAP are gmanpre, cfpost_prod, and madcapprod, respectively.

    The $WIND_DEV/SYSTEM/SYSTEM_CPU/bin directory will contain the executables for the various tools if the compilation is successful.

  15. Copy the executable and library files from the build directory to the application directory where they will be used. This is done via the command:

       make install_tools
    

    This copies the tools executables to $TOOLSROOT/SYSTEM/CPU/bin, where SYSTEM and CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, as described in step 11 in the procedure for building Wind-US.

  16. It would be best to log out and log back in again before running any of the tools. This executes the shell start-up scripts, modifying the PATH environment variable to include the newly-created location for the tools executables.

Tips for Installing on a UNIX System

Using Symbolic Links for Similar Systems

In general, it is recommended to compile executables on each machine type that you will use. However, in some situations two machines may be similar enough that the same executable can be used with only a minor degradation in performance. In that case, symbolic links may be used to specify that a different (but compatible) executable should be used instead.

Suppose you have compiled executables for a LINUX64-GLIBC2.5 system with a XEON processor, but would also like to provide binaries for OPTERON processors. You can share the available executable by creating a symbolic link. The Wind-US, PVM, and tools executables are stored in a directory hierarchy designated by the SYSTEM and SYSTEM\_CPU environment variables. Symbolic links must be created in the appropriate locations within the wind, wind/pvm, and tools subdirectories. For the case described, the easiest mechanism for sharing the executables is to create a symbolic link between the XEON and OPTERON directories.

   ln -s XEON OPTERON

The resulting directory structure will be:

   wind_install/
      wind/
         LINUX64-GLIBC2.5/
            XEON/
            OPTERON -> XEON/
            ...
         bin/
            ...
         pvm/
            lib/
               LINUX64-GLIBC2.5/
                  XEON
                  OPTERON -> XEON/
                  ...
      tools/
         LINUX64-GLIBC2.5/
            XEON/
            OPTERON -> XEON/
            ...
         bin/
            ...

where the notation "OPTERON -> XEON/" is used to indicate that OPTERON is a symbolic link pointing to XEON/.

Installation for NFS Access

If multiple users in an organization will be running Wind-US, it is convenient to install the Wind-US and tools executables below a parent directory that can be accessed by all the users via a network file system (NFS). This way, the location and method of accessing the executables will be the same on all user machines, and they can be centrally updated without any significant effort from individual users. It is suggested that one individual from an organization download the needed application distributions and serve as a single point of contact for Wind-US.

When the scripts and executables are to be accessed via NFS, if the path name used by the user to access the NFS-mounted file system is different from the actual directory name on the "host" system, a slight variation of the above installation procedure is necessary. That's because the user's environment variables CFDROOT and TOOLSROOT must define the NFS-mounted location of the wind and tools subdirectories. Similarly, the lines users add to their .login or .profile files should specify path names used to access the NFS-mounted file system.

NFS file systems are typically accessed using automount. As an example, assume that Wind-US and the tools have been installed on a host workstation named wind_machine, and that the parent installation directory is /usr/local/wind_nfs. On wind_machine, that directory is exported read-only to the "home" system, normally an individual's workstation, of each Wind-US user. The user can then access that directory via automount by adding "/net/wind_machine" to the beginning of the path name. E.g.,

   cd /net/wind_machine/usr/local/wind_nfs

The cfd.login, etc., files on wind_machine should be copied to new files named cfd.nfs.login, etc. [This is done so that users logging directly onto wind_machine can still access Wind-US as described in the previous sections.] The definitions of CFDROOT and TOOLSROOT in cfd.nfs.login, etc., should be modified to point to the automount'ed location of the wind and tools subdirectories. I.e., in cfd.nfs.login CFDROOT is defined as

   setenv CFDROOT /net/wind_machine/usr/local/wind_nfs/wind

and in tools.nfs.login TOOLSROOT is defined as

   setenv TOOLSROOT /net/wind_machine/usr/local/wind_nfs/tools

Finally, using the above example, csh and tcsh users accessing Wind-US via automount would modify their .login file to add the lines

   source /net/wind_machine/usr/local/wind_nfs/wind/bin/cfd.nfs.login
   source /net/wind_machine/usr/local/wind_nfs/tools/bin/tools.nfs.login

and sh and ksh users would modify their .profile file to add the lines

   . /net/wind_machine/usr/local/wind_nfs/wind/bin/cfd.nfs.profile
   . /net/wind_machine/usr/local/wind_nfs/tools/bin/tools.nfs.profile

Users accessing via NFS would not need to set the WIND\_DEV environment variable, since they would not be compiling the source code.

Installation for Parallel Execution on Distributed Systems

It should be noted that Wind-US does not need to be installed on each individual machine in order to run in parallel mode using a network of distributed systems. The executables for all the different types of systems and CPUs being used are installed only on the master system. The Wind-US run scripts automatically take care of copying the appropriate Wind-US and PVM executables and files to the systems being used, starting and stopping the message passing software, and cleaning up at the end of the run. See the Parallel Processing section of the Wind-US User's Guide for details.

When using MPI for parallel communication, the MPI libraries should be installed on each worker machine.


Last updated 30 Sep 2016