ast_linkast_link - Link a program with the AST library

Description:
This command should be used when building programs which use the AST library, in order to generate the correct arguments to allow the compiler to link your program. The arguments generated are written to standard output but may be substituted into the compiler command line in the standard UNIX way using backward quotes (see below).

By default, it is assumed that you are building a stand-alone program which does not produce graphical output. However, switches are provided for linking other types of program.

Invocation:
cc program.c -L/star/lib `ast_link [switches]` -o program
Examples:
cc display.c -L/star/lib `ast_link -pgplot` -o display

Compiles and links a C program called ``display'' which uses the standard version of PGPLOT for graphical output.
cc plotit.c -L. -L/star/lib `ast_link -grf` -lgrf -o plotit

Compiles and links a C program ``plotit''. The ``-grf'' switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by the current version of AST. Here, this interface is supplied by means of the ``-lgrf'' library reference.
cc plotit.c -L. -L/star/lib `ast_link -grf_v2.0` -lgrf -o plotit

Compiles and links a C program ``plotit''. The ``-grf_v2.0'' switch indicates that graphical output will be delivered through a graphical interface which you have implemented yourself, which corresponds to the interface required by version 2.0 of AST. Here, this interface is supplied by means of the ``-lgrf'' library reference.
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.

  • ``-ems'': Requests that the program be linked so that error messages produced by the AST library are delivered via the Starlink EMS (Error Message Service) library (Starlink SystemSystem Note SSN/4). By default, error messages are simply written to standard error.

  • ``-drama'': Requests that the program be linked so that error messages produced by the AST library are delivered via the DRAMA Ers (Error Reporting Service) library. By default, error messages are simply written to standard error.

  • ``-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.

  • ``-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 2D 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 2D 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 2D 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.
ERFA & PAL
The AST distribution includes bundled copies of the ERFA and PAL libraries. These will be used for fundamental positional astronomy calculations unless the "-with-external_pal" option was used when AST was configured. If "-with-external_pal" is used, this script will include "-lpal" in the returned list of linking options, and the user should then ensure that external copies of the PAL and ERFA libraries are available (ERFA functions are used within PAL).