path: root/ast/ast_link_adam

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

#  Purpose:
#     Link an ADAM program with the AST library.

#  Type of Module:
#     Shell script.

#  Description:
#     This command should only be used when building Starlink ADAM programs
#     which use the AST library, in order to generate the correct arguments
#     to allow the ADAM ``alink'' command to link the program. The arguments
#     generated are written to standard output but may be substituted into
#     the ``alink'' command line in the standard UNIX way using backward
#     quotes (see below).
#
#     By default, it is assumed that you are building an ADAM program which
#     does not produce graphical output. However, switches are provided for
#     linking other types of program. This command should not be used when
#     building stand-alone (non-ADAM) programs. Use the ``ast_link'' command
#     instead.

#  Invocation:
#c     alink program.o -L/star/lib `ast_link_adam [switches]`
#f     alink program.f -L/star/lib `ast_link_adam [switches]`

#  Switches:
#     The following switches may optionally be given to this command to
#     modify its behaviour:
#
#     - ``-csla'': Ignored. Provided for backward compatibility only.
#
#     - ``-fsla'': Ignored. Provided for backward compatibility only.
#
#     - ``-grf'': Requests that no arguments be generated to specify which
#     2D graphics system is used to display output from the AST library. You
#     should use this option only if you have implemented an interface to a
#     new graphics system yourself and wish to provide your own arguments for
#     linking with it. This switch differs from the other ``grf'' switches in
#     that it assumes that your graphics module implements the complete
#     interface required by the current version of AST. If future versions of
#     AST introduce new functions to the graphics interface, this switch will
#     cause ``unresolved symbol'' errors to occur during linking, warning you
#     that you need to implement new functions in your graphics module. To
#     avoid such errors, you can use one of the other, version-specific,
#     switches in place of the ``-grf'' switch, but these will cause run-time
#     errors to be reported if any AST function is invoked which requires
#     facilities not in the implemented interface.
#
#     - ``-grf_v2.0'': This switch is equivalent to the ``-mygrf'' switch.
#     It indicates that you want to link with your own graphics module which
#     implements the 2D graphics interface required by V2.0 of AST.
#
#     - ``-grf_v3.2'': Indicates that you want to link with your own graphics
#     module which implements the 2D graphics interface required by V3.2 of AST.
#
#     - ``-grf_v5.6'': Indicates that you want to link with your own graphics
#     module which implements the 2D graphics interface required by V5.6 of AST.
#
#     - ``-myerr'': Requests that no arguments be generated to specify how
#     error messages produced by the AST library should be delivered. You
#     should use this option only if you have implemented an interface to a
#     new error delivery system yourself and wish to provide your own
#     arguments for linking with it. By default, error messages are delivered
#     in the standard ADAM way via the EMS Error Message Service (Starlink
#     System Note SSN/4).
#
#     - ``-mygrf'': This switch has been superceeded by the ``-grf'' switch,
#     but is retained in order to allow applications to be linked with a
#     graphics module which implements the interface used by AST V2.0. It is
#     equivalent to the ``-grf_v2.0'' switch.
#
#     - ``-pgp'': Requests that the program be linked so that 2D
#     graphical output from the AST library is displayed via the
#     Starlink version of the PGPLOT graphics package (which uses GKS
#     for its output). By default, no graphics package is linked and
#     this will result in an error at run time if AST routines are
#     invoked that attempt to generate graphical output.
#
#     - ``-pgplot'': Requests that the program be linked so that 2D
#     graphical output from the AST library is displayed via the
#     standard (or ``native'') version of the PGPLOT graphics
#     package. By default, no graphics package is linked and this will
#     result in an error at run time if AST routines are invoked that
#     attempt to generate graphical output.
#
#     - ``-grf3d'': Requests that no arguments be generated to specify which
#     3D graphics system is used to display output from the AST library. You
#     should use this option only if you have implemented an interface to a
#     new 3D graphics system yourself and wish to provide your own arguments
#     for linking with it.
#
#     - ``-pgp3d'': Requests that the program be linked so that 3D
#     graphical output from the AST library is displayed via the
#     Starlink version of the PGPLOT graphics package (which uses GKS
#     for its output). By default, no 3D graphics package is linked and
#     this will result in an error at run time if AST routines are
#     invoked that attempt to generate graphical output.
#
#     - ``-pgplot3d'': Requests that the program be linked so that 3D
#     graphical output from the AST library is displayed via
#     the standard (or ``native'') version of the PGPLOT graphics
#     package. By default, no 3D graphics package is linked and this will
#     result in an error at run time if AST routines are invoked that
#     attempt to generate graphical output.

#  SLALIB:
#     The AST distribution includes a cut down subset of the C version of
#     the SLALIB library written by Pat Wallace. This subset contains only
#     the functions needed by the AST library. It is built as part of the
#     process of building AST and is distributed under GPL (and is thus
#     compatible with the AST license). Previous version of this script
#     allowed AST applications to be linked against external SLALIB
#     libraries (either Fortran or C) rather than the internal version.
#     The current version of this script does not provide this option,
#     and always uses the internal SLALIB library. However, for backward
#     compatibility, this script still allows the "-fsla" and "-csla" flags
#     (previously used for selecting which version of SLALIB to use) to be
#     specified, but they will be ignored.

#  Examples:
#c     alink display.o -L/star/lib `ast_link_adam -pgplot`
#c        Links an ADAM program ``display'' which uses the standard
#c        version of PGPLOT for graphical output.
#c     alink plotit.o -L. -L/star/lib `ast_link_adam -grf` -lgrf
#c        Links an ADAM program ``plotit'', written in C. The ``-grf''
#c        switch indicates that graphical output will be delivered through
#c        a graphical interface which you have implemented yourself, which
#c        corresponds to the interface required by the current version of AST.
#c        Here, this interface is supplied by means of the ``-lgrf'' library
#c        reference.
#c     alink plotit.o -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf
#c        Links an ADAM program ``plotit'', written in C. The ``-grf_v2.0''
#c        switch indicates that graphical output will be delivered through
#c        a graphical interface which you have implemented yourself, which
#c        corresponds to the interface required by version 2.0 of AST. Here,
#c        this interface is supplied by means of the ``-lgrf'' library
#c        reference.
#f     alink display.f -L/star/lib `ast_link_adam -pgplot`
#f        Compiles and links an ADAM Fortran program called ``display'' which
#f        uses the standard version of PGPLOT for graphical output.
#f     alink plotit.f -L. -L/star/lib `ast_link_adam -grf` -lgrf
#f        Compiles and links an ADAM Fortran program ``plotit''. The ``-grf''
#f        switch indicates that graphical output will be delivered through
#f        a graphical interface which you have implemented yourself, which
#f        corresponds to the interface required by the current version of AST.
#f        Here, this interface is supplied by means of the ``-lgrf'' library
#f        reference.
#f     alink plotit.f -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf
#f        Compiles and links an ADAM Fortran program ``plotit''. The ``-grf_v2.0''
#f        switch indicates that graphical output will be delivered through
#f        a graphical interface which you have implemented yourself, which
#f        corresponds to the interface required by version 2.0 of AST.
#f        Here, this interface is supplied by means of the ``-lgrf'' library
#f        reference.

#  Copyright:
#     Copyright (C) 1997-2006 Council for the Central Laboratory of the Research Councils

#  Authors:
#     RFWS: R.F. Warren-Smith (STARLINK)
#     {enter_new_authors_here}

#  History:
#     11-NOV-1996 (RFWS):
#        Original version.
#     18-NOV-1997 (RFWS):
#        Adapted prologue for document extraction.
#     28-SEP-1998 (RFWS):
#        Distinguish between -pgp and -pgplot options.
#     23-JAN-2004 (DSB):
#        Added switches to support older grf implementations.
#     21-APR-2005 (DSB):
#        Added "-fsla" option.
#     16-JUN-2006 (DSB):
#        Ignore "-fsla" and "-clsa" options, and always use PAL.
#     22-AUG-2007 (DSB):
#        Added "-grf3d", "-pgplot3d" and "-pgp3d" flags.
#     4-MAR-2011 (DSB):
#        Added v5.6 grf options.
#     {enter_changes_here}

#  Bugs:
#     {note_any_bugs_here}

#--

#  This function searches the directory path specified in PATH, looking for
#  an executable file which is not a directory. If found, it echos the full
#  file name to standard output. Otherwise, it outputs nothing.
      find() { IFS=':'; for d in $PATH; do f="${d:=.}/${1}"
                  test -x "${f}" -a ! -d "${f}" && echo "${f}" && break
               done;
             }

#  Initialise linking options.
      err=''
      grf=''
      grf3d=''
      sla=''

#  Interpret command line switches.
#  --------------------------------
      while :; do
         case "${1}" in

#  -csla - Previously used to request C version of SLALIB. Now ignored.
         -csla)
#            sla='c'
            shift;;

#  -fsla - Previously used to request Fortran version of SLALIB. Now ignored.
         -fsla)
#            sla='f'
            shift;;

#  -myerr - Requests no error reporting.
         -myerr)
            err='my'
            shift;;

#  -grf - Requests no 2D graphics.
         -grf)
            grf='current'
            shift;;

#  -mygrf - Requests no 2D graphics, except for null implementations of
#  functions aded to the grf interface after AST V2.0.
         -mygrf)
            grf='v2.0'
            shift;;

#  -grf_v2.0 - Requests no 2D graphics, except for null implementations of
#  functions aded to the grf interface after AST V2.0.
         -grf_v2.0)
            grf='v2.0'
            shift;;

#  -grf_v3.2 - Requests no 2D graphics, except for null implementations of
#  functions aded to the grf interface after AST V3.2.
         -grf_v3.2)
            grf='v3.2'
            shift;;

#  -grf_v5.6 - Requests no 2D graphics, except for null implementations of
#  functions added to the grf interface after AST V5.6.
         -grf_v5.6)
            grf='v5.6'
            shift;;

#  -pgp - Requests 2D graphical output through Starlink PGPLOT.
         -pgp)
            grf='pgp'
            shift;;

#  -pgplot - Requests 2D graphical output through native PGPLOT.
         -pgplot)
            grf='pgplot'
            shift;;

#  -grf3d - Requests no 3D graphics.
         -grf3d)
            grf3d='current'
            shift;;

#  -pgp3d - Requests 3D graphical output through Starlink PGPLOT.
         -pgp3d)
            grf3d='pgp'
            shift;;

#  -pgplot3d - Requests 3D graphical output through native PGPLOT.
         -pgplot3d)
            grf3d='pgplot'
            shift;;

#  Once all switches have been read, continue with the rest of the script.
         '') break;;

#  Catch unrecognised switches and report an error.
         *)
            echo >&2 "ast_link_adam: unknown argument \""${1}"\" given"
            exit 1;;
         esac
      done

#  Link with the main AST library.
#  -------------------------------
#  Start forming the list of arguments with the main AST library itself.
      args='-last'

#  Generate arguments for linking PAL.
#  -----------------------------------

      case "0" in

#  If we configured --with-external_pal include a link option to pick up
#  an external PAL library.
      1) args="${args} -lpal";;

#  Otherwise, use the internal PAL & ERFA libraries.
      *) args="${args} -last_pal";;

      esac

#  Generate arguments for linking the 2D graphics system.
#  ------------------------------------------------------
      case "${grf}" in

#  If using Starlink PGPLOT, link with the AST PGPLOT interface and
#  the Fortran library via the PGP link script.
      pgp) args="${args} -last_pgplot `pgp_link_adam`";;

#  If using native PGPLOT, link with the AST PGPLOT interface and
#  the Fortran library via the PGPLOT link script.
      pgplot) args="${args} -last_pgplot `pgplot_link_adam`";;

#  If using own graphics which conform to the requirements of the current
#  version of AST, do not produce any arguments.
      current) :;;

#  If using own graphics which conform to the requirements of version 5.6
#  of AST, produce arguments which link in dummy implementations of any
#  functions which are required by the current version of AST but which were
#  not required by version 5.6.
      v5.6) :;;

#  If using own graphics which conform to the requirements of version 3.2
#  of AST, produce arguments which link in dummy implementations of any
#  functions which are required by the current version of AST but which were
#  not required by version 3.2.
      v3.2) args="${args} -last_grf_5.6";;

#  If using own graphics which conform to the requirements of version 2.0
#  of AST, produce arguments which link in dummy implementations of any
#  functions which are required by the current version of AST but which were
#  not required by version 2.0.
      v2.0) args="${args} -last_grf_3.2 -last_grf_5.6";;

#  Default graphics (none) requires linking with all the default (null) AST
#  "grf" modules.
      *) args="${args} -last_grf_2.0 -last_grf_3.2 -last_grf_5.6";;
      esac

#  Generate arguments for linking the 3D graphics system.
#  ------------------------------------------------------
      case "${grf3d}" in

#  If using Starlink PGPLOT, link with the AST 3D PGPLOT interface and
#  the Fortran library via the PGP link script (if found).
      pgp) args="${args} -last_pgplot3d `\`find pgp_link\``"
           f77='y';;

#  If using native PGPLOT, link with the AST 3D PGPLOT interface and the
#  Fortran library via the PGPLOT link script (if found).
      pgplot) args="${args} -last_pgplot3d `\`find pgplot_link\``"
              f77='y';;

#  If using own 3D graphics which conform to the requirements of the current
#  version of AST, do not produce any arguments.
      current) :;;

#  Default graphics (none) requires linking with all the default (null) AST
#  "grf3d" modules.
      *) args="${args} -last_grf3d";;
      esac

#  Make a second pass through the AST library.
#  -------------------------------------------
#  This library is a link to the main AST library and results in a second
#  pass to resolve any backward references generated by the other modules
#  used above. A different library name must be used to avoid the two passes
#  being merged into one (either below, or by other link scripts).
      args="${args} -last_pass2"

#  Generate arguments for linking the error reporting system.
#  ----------------------------------------------------------
      case "${err}" in

#  If using own error reporting, do not produce any arguments.
      my) :;;

#  Default error reporting requires linking with the AST EMS interface and
#  the EMS library via the link script.
      *) args="${args} -last_ems `ems_link_adam`";;
      esac

#  Link with the maths library.
#  ----------------------------
      args="${args} -lm"

#  Link with the starmem library, if available.
#  --------------------------------------------
      args="${args} `\`find starmem_link\``"

#  Pass the resulting argument list through an awk script which eliminates
#  all except the last reference to each library.
      echo "${args}" \
           | awk 'BEGIN{RS=" ";FS="\n"}
                  {if($1)f[i++]=$1}
                  END{for(;i--;)if(!w[f[i]]++)l=f[i]" "l;print l}'

#  End of script.