
#  N.B. the previous line should be blank.
#+
#  Name:
#     mk

#  Purpose:
#     Invoke make to build and install the HDS package.

#  Type of Module:
#     Shell script.

#  Description:
#     This script should normally be used to invoke the make utility to
#     build and install the HDS package and to perform other
#     housekeeping tasks. It invokes the make utility after first
#     defining appropriate environment variables and macros for the
#     computer system in use. This file also serves to document the
#     systems on which HDS is implemented.

#  Invocation:
#     The user of this script should normally first define the SYSTEM
#     environment variable to identify the host computer system (see
#     the "Supported Systems" section). This script should then be used
#     in the same way as the make utility would be used. For instance,
#     to build, install and test HDS, you might use the following
#     commands:
#
#        mk build
#	 mk install
#	 mk test
#	 mk clean

#  Supported Systems:
#     The following UNIX systems are currently supported and may be
#     identified by defining the SYSTEM environment variable appropriately
#     before invoking this script:
#        alpha_OSF1
#           DEC Alpha machines running OSF1
#        sun4_Solaris
#           SUN Sparcstations running SunOS 5.x (Solaris)
#        ix86_Linux
#           Intel PC running Linux
#
#     The following systems have been supported in the past and the relevant
#     code has been retained. They may still work, or may work with only
#     minor repairs, but have not recently been tested.
#        HP9000_HP-UX
#           HP 9000 series machines running HP-UX
#        mips
#           DECstations running Ultrix
#        sun4
#           SUN Sparcstations running SunOS 4.x (GNU C compiler).
#        sun4_acc
#           SUN Sparcstations running SunOS 4.x (SUN ANSI C compiler)
#
#     This script will exit without action if the SYSTEM environment
#     variable is not defined. A warning will be issued if it is
#     defined but is not set to one of the values above. In this case,
#     no additional environment variables will be defined by this
#     script (any that are pre-defined will be passed on to make
#     unaltered).

#  External Dependencies:
#     The HDS package depends on the following other Starlink packages
#     which must previously have been installed into the appropriate
#     sub-directories of the $STARLINK directory (/star is used if the
#     environment variable STARLINK is not defined).
#        chr
#           Character handling routines
#        cnf
#           C <-> Fortran interface macros and routines
#        ems
#           Error message service
#        sae_par
#           Global include files

#  Targets:
#     The following targets are provided in the associated makefile for
#     use via this script:
#     
#        [help]
#	    This is the default target. It outputs a message describing
#	    this script and lists the targets provided.
#        check
#	    Performs a simple check that all necessary source files are
#	    present, and displays the version number and current state
#	    of the package (built/installed/tested, etc.).
#        build
#	    Compiles the source files and creates all files needed
#	    prior to installing the package for use.
#        install
#	    Installs the package for use by putting the necessary files
#	    into sub-directories of the $INSTALL directory (the $HOME
#	    directory is used if the environment variable INSTALL is
#	    not defined). Links to the installed files are left in the
#	    source directory.
#        deinstall
#	    Reverses the action of the install target, removing files
#	    from sub-directories of the $INSTALL directory and
#	    restoring them to the source directory (the $HOME directory
#	    is used by default if the environment variable INSTALL is
#	    not defined).
#        test
#	    Builds and runs a simple test program to check for correct
#	    installation of the package.
#        export
#	    Produces an export copy of the built package suitable for
#	    passing to another user. A compressed tar file is created
#	    in the $EXPORT directory containing copies of the source
#	    files and built files for the package (the current
#	    directory is used by default if the environment variable
#	    EXPORT is not defined). The package should normally be
#	    built, installed and tested before using this target. After
#	    unpacking the exported file on a similar machine, the
#	    recipient may simply install it for use.
#        export_source
#	    Produces an export copy of the source for the package
#	    suitable for passing to another user to build (possibly on
#	    a different type of machine). A compressed tar file is
#	    created in the $EXPORT directory containing copies of just
#	    the source files for the packge (the current directory is
#	    used by default if the environment variable EXPORT is not
#	    defined). After unpacking the exported file, the recipient
#	    must build the package before installing it for use.
#        clean
#	    Cleans up after building the package, removing all
#	    intermediate files created during the building process, but
#	    leaving the built files themselves.
#        unbuild
#	    Reverses the building process, removing all intermediate
#	    files along with all the built files.

#  Notes on Porting:
#     If your machine or system setup does not appear in this script,
#     then it may be possible to build and install HDS by adding a new
#     case to this script with appropriate definitions (probably based
#     on one of the existing implementations). Your chances of
#     installing HDS on a hitherto unsupported machine are good if it
#     has a reasonable Fortran 77 compiler, an ANSI C compiler, IEEE or
#     VAX floating point number format and provides a POSIX.1
#     programming interface to system calls. You must also have
#     previously installed the other Starlink packages on which HDS
#     depends (see the "External Dependencies" section).
#
#     This script invokes the make utility with a description file
#     (makefile) which makes use of certain pre-defined macros which
#     accommodate the variations between different machines and
#     operating systems. The C source code of HDS also contains macros
#     which allow it to adapt to certain common machine
#     characteristics. Each of these (make and C) macros has a default
#     which assumes notional (approximately POSIX) machine
#     characteristics. If your system differs from this, or if it
#     provides additional facilities that you want to exploit, then you
#     can change these macro definitions as necessary.
#
#     You can re-define macros used by the make utility by defining
#     appropriate environment variables (when make is invoked via this
#     script, the -e option is used, so these definitions over-ride
#     make macros of the same name). C macros should be defined using
#     the appropriate C compiler option (-D on most compilers) as part
#     of the CFLAGS make macro. To document your implementation, these
#     definitions should normally be added to this script, although you
#     can also define environment variables externally if required.

#  make Macros:
#     The following "global" make macros are used in the associated
#     makefile and may be changed by means of appropriate environment
#     variable definitions (in each case the default is shown in
#     parentheses). Note that these macros are provided to allow
#     external control over the directories in which software is
#     installed, etc., so they should not normally be re-defined within
#     this script.
#     
#        STARLINK (/star)
#	    Pathname of the root directory beneath which Starlink
#	    software is currently installed. This indicates to HDS
#	    where to find other Starlink software (include files,
#	    libraries, etc.) which it uses.
#        INSTALL ($HOME)
#	    Pathname of the root directory beneath which HDS will be
#	    installed for use. Your home directory will be used by
#	    default. This macro is provided to allow HDS to be
#	    installed locally for personal use (e.g. during development
#	    or testing). It should be set to the $STARLINK directory if
#	    you want to add HDS into an already installed set of
#	    Starlink software. You should ensure that the appropriate
#	    sub-directories appear on any relevant search paths which
#	    your system uses for locating software (e.g. binaries and
#	    libraries).
#        EXPORT (.)
#	    Pathname of the directory into which compressed tar files
#	    will be written if the "export" or "export_source" make
#	    targets are used to produce an exportable copy of HDS or
#	    its source files. The current working directory (i.e. the
#	    HDS source directory) will be used by default.
#
#     The following "local" make macros are used in the associated
#     makefile and should normally be over-ridden (when appropriate) by
#     environment variable definitions within this script. In each case
#     the default is shown in parentheses.
#
#        AR_IN (ar -r)
#	    The command to use to insert an object (.o) file into an
#	    archive (.a) library. On some systems the variation 'ar r'
#	    may be required instead.
#        BLD_SHR (:)
#           Command to build a shareable library when given three
#           arguments specifying (1) the name of the library file to be
#           built (2) a list of the object files to be used in the
#           library and (3) a list of any additional libraries against
#           which to link. By default, it is assumed that shareable
#           libraries are not available, and the default acts as a null
#           command.
#        CC (c89)
#	    The C compiler command to use. HDS requires an ANSI C
#	    compiler, although other compilers may be acceptable so
#	    long as they support function prototyping (VAX C for
#	    instance). Users of GNU C should be aware that the ANSI
#	    versions of include files are required, and that problems
#	    may be encountered with GNU C if your C run-time library
#	    departs from ANSI behaviour. POSIX.1 C include files should
#	    also be available.
#        CFLAGS (-O)
#	    The C compiler options to use. These may include C macro
#	    definitions (e.g. using the -D option on most compilers).
#        FC (fort77)
#	    The Fortran compiler command to use. HDS requires a Fortran
#	    77 compiler that supports the common "permitted" Starlink
#	    extensions, as documented in Starlink General Paper SGP/16.
#	    (These include only the most common extensions, such as
#	    long names, end of line comments, include files, etc. The
#	    DEC Fortran %VAL facility is also used, but only by the
#	    installation test program.)
#        FFLAGS (-O)
#	    The Fortran compiler options to be used.
#        KNOWN (0)
#	    This should be set to '1' if the platform on which HDS is
#	    being built is known and it has been checked that HDS
#	    correctly recognises the data representations which it
#	    uses. If this value is undefined or is set to any other
#	    string, then a message will be issued when HDS is built
#	    warning of the need to make this check before putting HDS
#	    into use.
#        LINK (ln)
#	    The command required to establish a link to a file. The
#	    default assumes POSIX.2 behavior, which only provides a
#	    "hard" link operating within a single file system. If the
#	    host operating system allows "symbolic" links, then this
#	    macro might be re-defined as 'ln -s'. Alternatively, if the
#	    use of multiple file systems is essential but not supported
#	    by any form of link, then a copy command could be
#	    substituted (e.g. 'cp -p'), at some cost in file space.
#        RANLIB (:)
#	    The command required to "randomise" an object library. By
#	    default, this operation is not performed (the default acts
#	    as a null command). On systems which require it, this
#	    should typically be set to 'ranlib'.
#        SHARE (.so)
#           The file type suffix to be applied to produce the name of a
#           shareable library file. By default, the ".so" suffix is
#           applied without a library version number. For systems which
#           support version numbers on shareable libraries, the macro
#           LIB_VERS is defined within the associated makefile and may
#           be used as part of a definition such as '.so.$(LIB_VERS)'.
#	 TAR_IN (pax -w -v -x ustar -f)
#	    Command to use to insert a file into a .tar archive file.
#	    The default uses the POSIX.2 pax command, which is not
#	    available on traditional UNIX systems. These typically use
#	    a tar command such as 'tar -cvhf' instead (if symbolic
#	    links are supported, then an option to follow these must be
#	    included in this command).
#	 TAR_OUT (pax -r -f)
#	    Command to use to extract a file from a .tar archive file.
#	    The default uses the POSIX.2 pax command, which is not
#	    available on traditional UNIX systems. These typically use
#	    a tar command such as 'tar -xf' instead.

#  C Macros:
#     These macros appear in the C source code for HDS and should be
#     defined as required using the appropriate compiler option (as
#     part of the CFLAGS make macro). By default, none of these macros
#     is pre-defined.
#
#     This first set of macros, if defined, select machine-specific
#     code which is generally essential for a particular
#     implementation. The appropriate one of these macros must
#     therefore be defined if you are using one of these systems. If
#     none of these macros is defined (the default), then a generic
#     POSIX.1 operating system interface is assumed (as modified by the
#     additional macros discussed below):
#
#        _sun4_Solaris
#           SUN Sparcstations running SunOS 5.x (Solaris)
#        sun4
#           SUN Sparcstations running SunOS 4.x.
#        vms
#           VAX systems running VMS
#
#     The following set of macros may be defined, as required, to
#     enable or select these additional features:
#
#     _longd
#	 By default, HDS will not attempt to use the ANSI C long double
#	 data type. This is because some compilers which claim to be
#	 ANSI (and define __STDC__ = 1) nevertheless do not recognise
#	 this data type. This will almost never cause a problem unless
#	 long double is one of the data types defined as part of the
#	 C<->Fortran interface in the include file f77.h. If long
#	 double ever needs to be used and the compiler is capable of
#	 handling it, then it can be enabled by defining this macro (to
#	 any value).
#     _mmap
#	 This macro may be defined (to any value) to indicate that the
#	 host machine supports file mapping via mmap and munmap calls
#	 (based on the POSIX.4 definition of these functions) and
#	 that HDS should use them for file access when required. If
#	 your machine has these functions, then it is likely (although
#	 not certain) that they will be OK. However, at present, this
#	 macro should NOT be defined unless the system page size
#	 matches the logical block size of HDS files (512 bytes). This
#	 restriction might be removed in future.
#     _noalign
#	 This macro should remain undefined if (a) the Fortran compiler
#	 which will be used to compile applications calling HDS
#	 generates DOUBLE PRECISION values which are not aligned on C
#	 double boundaries (this is true for most ANSI Fortran 77
#	 compilers which may need to align DOUBLE PRECISION variables
#	 with REAL variables, e.g. in common blocks), and (b) the C
#	 compiler/machine hardware cannot perform arithmetic on such
#	 badly-aligned double values. Otherwise, it should be defined
#	 (with any value), and will prevent HDS from making an aligned
#	 copy of DOUBLE PRECISION values before use.
#
#	 If you omit this option when it is required, you may suffer a
#	 small efficiency penalty. If you supply it when it is not
#	 required, you may obtain addressing errors or arithmetic
#	 exceptions when using HDS to access DOUBLE PRECISION data.
#
#	 Note that some C compilers have their own option to permit
#	 them to handle mis-aligned variables passed from Fortran. If
#	 available, this option should be used. The _noalign macro
#	 should then also be defined.
#     _vfork
#	 If this macro is defined (to any value), then the vfork
#	 function will be used, when appropriate, to create child
#	 processes. This may be more efficient on those systems which
#	 support this function. By default, the POSIX.1 fork function
#	 is used.
#     _sh
#	 If defined, this macro specifies the command to be used to
#	 invoke the sh shell on UNIX systems. It should be set equal to
#	 the appropriate character string (e.g. "sh5"). If it is
#	 undefined, then the string "sh" is used instead. The sh shell
#	 is invoked by HDS when selected via the HDS_SHELL tuning
#	 option (it is, in fact, the default) and is used to to perform
#	 file name expansion. An implementation of this shell which
#	 supports the 'set -f' and 'set +f' commands is required. HDS
#	 will search for the specified shell using the directory list
#	 given by the PATH environment variable. Note that if your
#	 system supports POSIX.2 (shell and utilities), then HDS will
#	 first attempt to use the standard POSIX.2 sh shell regardless
#	 of the value of this macro.
#
#	 If you omit this option when it is required, or if you specify
#	 an inappropriate command, HDS may not be able to identify
#	 files which it is asked to open or create. The effects of this
#	 will be most obvious when referring to files whose names
#	 contain references to environment variables, or when using the
#	 "wild_carding" facilities.
#     _csh
#	 If defined, this macro specifies the command to be used to
#	 invoke the csh shell on UNIX systems. Its use is identical to
#	 the _sh macro, except that this is not the default shell and
#	 must be selected via the HDS_SHELL tuning parameter if it is
#	 required. In this case the default command used is "csh".
#	 There is no POSIX.2 equivalent.
#
#	 If your system does not have a csh shell, then it is
#	 recommended that this macro be defined to invoke the sh shell
#	 instead.
#     _tcsh
#	 If defined, this macro specifies the command to be used to
#	 invoke the tcsh shell on UNIX systems. Its use is identical to
#	 the _sh macro, except that this is not the default shell and
#	 must be selected via the HDS_SHELL tuning parameter if it is
#	 required. In this case the default command used is "tcsh".
#	 There is no POSIX.2 equivalent.
#
#	 If your system does not have a tcsh shell, then it is
#	 recommended that this macro be defined to invoke the same
#	 shell as the _csh macro.

#  Data Representation:
#     HDS is potentially capable of reading/writing files in which data
#     values are encoded in a variety of ways, corresponding with
#     common hardware capabilities and compiler preferences. However,
#     no options are provided for directly specifying the data formats
#     used by the host machine.
#
#     Instead, HDS obtains this information itself. Part of this comes
#     from macros defined in the f77.h include file (part of the
#     Starlink cnf package which describes the Fortran <-> C
#     interface). These specify which C data types correspond to which
#     Fortran-accessible HDS types (_INTEGER, _REAL, _DOUBLE, etc.) and
#     also give information about the encoding of _LOGICAL values
#     (normally a characterisic of the Fortran compiler rather than the
#     hardware). HDS determines any further information it needs from
#     the standard ANSI C include files (<limits.h> and <float.h>) and
#     from tests performed on actual data values at run-time.
#
#     HDS should currently be able to recognise and adapt to machines
#     whose Fortran 77 implementation uses data formats satisfying the
#     following requirements, so long as the appropriate definitions
#     are present in f77.h:
#
#        -  8 bit bytes.
#
#	 -  Integer data encoded using 2's complement (for signed
#	 types) and binary (for unsigned types).
#
#	 -  Integer data having lengths in bytes of 1 (_BYTE), 2
#	 (_WORD) and 4 (_INTEGER).
#
#	 -  Floating point data encoded using IEEE single precision or
#	 VAX F-floating format (for single precision) and IEEE double
#	 precision or VAX D-floating format (for double precision).
#
#	 -  Logical data encoded .FALSE./.TRUE. using either an integer
#	 value of zero/non-zero, or using just the least significant
#	 bit set to 0/1.
#
#        -  Big-endian or little-endian byte order.
#
#        -  ASCII encoding of characters.
#
#     If support for additional data formats is required, then coding
#     changes within HDS will be necessary. If you perform such
#     changes, then please consider making your code (especially any
#     new format conversion algorithms) available for distribution via
#     Starlink. This will allow others to read your new-format files.
#
#  IMPORTANT NOTE:
#      If HDS is used with inappropriate settings for the native
#      machine data representation, then it may not be possible to read
#      the resulting data files with HDS on other machines. This fact
#      could potentially go unnoticed for some time. Because of this
#      danger, the file hds_datestamp, which is produced as part of the
#      process of building HDS, contains a record of what HDS believes
#      to be the data representation used by the Fortran 77
#      implementation of the host machine. It should be checked
#      carefully before putting HDS into use on any new system.

#  Implementation Deficiencies:
#     -  The implementation of shareable libraries on the alpha_OSF1
#     system is still preliminary.
#     -  The -Dmips option in CFLAGS for Ultrix is a temporary measure
#     to overcome a problem in the f77.h include file if the -std option
#     is also used. The -Dmips should eventually be removed.

#  Copyright:
#     Copyright (C) 1992 Science & Engineering Research Council

#  Authors:
#     RFWS: R.F. Warren-Smith (STARLINK, RAL)
#     BKM: B.K.McIlwrath (Starlink, RAL)
#     {enter_new_authors_here}

#  History:
#     25-AUG-1992 (RFWS):
#        Original version.
#     7-DEC-1992 (RFWS):
#        Extended the prologue.
#     11-DEC-1992 (RFWS):
#     	 Converted to an sh shell script.
#     16-DEC-1992 (RFWS):
#     	 Added more environment variables.
#     6-JUL-1993 (RFWS):
#        Updated for the alpha_OSF1 system.
#     8-FEB-1994 (RFWS):
#     	 Added HP9000_HP-UX implementation.
#     1-JUN-1995 (RFWS):
#        Updated the compiler options for _alpha_OSF1 and sun4_Solaris
#        systems.
#     5-DEC-1995 (BKM):
#        Linux support added.
#     9-MAY-1997 (RFWS):
#        Restored lost Linux CFLAGS value.
#     {enter_further_changes_here}

#  Bugs:
#     {note_any_bugs_here}

#-

#.

#  Export "local" definitions to the environment for use by make.
      export AR_IN
      export BLD_SHR
      export CC
      export CFLAGS
      export FC
      export FFLAGS
      export KNOWN
      export LINK
      export RANLIB
      export SHARE
      export TAR_IN
      export TAR_OUT

#  Check that the SYSTEM environment variable is defined.
      if test "$SYSTEM" = ""; then
         echo "mk: Please define the environment variable SYSTEM to identify"
         echo "    your computer system (the prologue in the mk script file"
         echo "    contains more information if you require it)."

#  If OK, then initially assume that the system is unknown. Test for
#  each recognised system.
      else
         KNOWN='0'
         case "$SYSTEM" in

#  HP 9000 series machines running HP-UX:
#  =====================================
            HP9000_HP-UX)
               CFLAGS='-O -D_noalign'
               FFLAGS-'-O'
               KNOWN='1'
               LINK='ln -s -f'
               echo "mk: Environment variables defined for $SYSTEM system"
	       ;;

#  DEC Alpha:
#  =========
#  DEC Alpha machines running OSF1:
#  -------------------------------
            alpha_OSF1)
               AR_IN='ar rls'
               BLD_SHR=':'
#               BLD_SHR=\
#'f() ld -shared -update_registry $(INSTALL)/lib/so_locations -o $$1 $$2 $$3 \
#-lfor -lFutil -lUfor -lm -lots -lc; f'
               CC='cc'
               CFLAGS='-std1 -O -Olimit 800 -D_noalign -D_mmap'
               FC='f77'
               FFLAGS='-O -w'
               KNOWN='1'
               LINK='ln -f -s'
               RANLIB=':'
               SHARE='.so'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
	       ;;

#  DECstations:
#  ===========
#  DECstations running Ultrix.
#  --------------------------
            mips)
               BLD_SHR=':'
               CC='cc'
               CFLAGS='-std -Dmips -O -Olimit 800 -D_noalign -D_vfork -D_sh=\"sh5\"'
               FC='f77'
               FFLAGS='-O'
               KNOWN='1'
               LINK='ln -f -s'
               RANLIB='ranlib'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
	       ;;

#  SUN4 systems:
#  ============
#  SUN Sparcstations running SunOS 4.x.
#  -----------------------------------
            sun4)
               AR_IN='ar r'
               BLD_SHR='f() ld -assert pure-text -o $$1 $$2; f'
               CC='gcc'
               CFLAGS='-ansi -O2 -fPIC -Dsun4 -D_vfork -D_mmap'
               FC='f77'
               FFLAGS='-O -PIC'
               KNOWN='1'
               LINK='ln -s'
               RANLIB='ranlib'
               SHARE='.so.$(LIB_VERS)'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
               ;;

#  As above, but using Sun's ANSI compiler.
#  ---------------------------------------
#  (Normally only used for development work.)
            sun4_acc)
               AR_IN='ar r'
               BLD_SHR='f() ld -assert pure-text -o $$1 $$2; f'
               CC='acc'
               CFLAGS='-Xa -vc -O2 -PIC -Dsun4 -D_noalign -D_vfork -D_mmap'
               FC='f77'
               FFLAGS='-O -PIC'
               KNOWN='1'
               LINK='ln -s'
               RANLIB='ranlib'
               SHARE='.so.$(LIB_VERS)'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
               ;;

#  SUN Sparcstations running SunOS 5.x (Solaris).
#  ---------------------------------------------
            sun4_Solaris)
               AR_IN='ar -r'
               BLD_SHR='f() ld -G -z text -o $$1 $$2; f'
               CC='cc'
               CFLAGS='-Xc -v -O -KPIC -D_noalign -D_vfork -D_mmap -D_sun4_Solaris'
               FC='f77'
               FFLAGS='-O -PIC -silent'
               KNOWN='1'
               LINK='ln -f -s'
               RANLIB=':'
               SHARE='.so'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
               ;;

#  PC systems:
#  ==========
#  Intel PC running Linux.
#  ----------------------
            ix86_Linux)
               AR_IN='ar r'
               BLD_SHR='f() { ld -shared -soname $$1 -o $$1 $$2;}; f'
               CC='gcc'
               CFLAGS='-O2 -fPIC -D_noalign -D_vfork -D_mmap'
               FC='g77'
               FFLAGS='-fno-second-underscore -O2 -fPIC'
               KNOWN='1'
               LINK='ln -s'
               RANLIB='ranlib'
               SHARE='.so'
               TAR_IN='tar -cvhf'
               TAR_OUT='tar -xf'
               echo "mk: Environment variables defined for $SYSTEM system"
               ;;

#  Issue a warning if SYSTEM is not recognised.
	    *)
               echo "mk: WARNING: value of SYSTEM = $SYSTEM not recognised..."
               echo "             ...assuming default system characteristics"
               ;;
         esac

#  Invoke make with the appropriate environment variables set to over-ride
#  default macros defined in the makefile.
         echo make -e $*
         make -e $*
      fi

#  End of script.
