#
UNIX Command Descriptions

The commands described here are provided for use from the UNIX shell to assist with developing software which uses AST. To use these commands, you should ensure that the directory “/star/bin” is on your PATH. ast_link Link a program with the AST library 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. cc program.c -L/star/lib `ast_link [switches]` -o program 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). CMINPACK The AST distribution includes a bundled copy of the CMINPACK library. This will be used for various minimisation processes unless the " –with-external_cminpack" option was used when AST was configured. If " –with-external_cminpack" is used, this script will include " -lcminpack" in the returned list of linking options, and the user should then ensure that an external copy of the CMINPACK library is available. ast_link_adam Link an ADAM program with the AST library 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_linkast_link' ' command instead. alink program.o -L/star/lib `ast_link_adam [switches]` alink display.o -L/star/lib `ast_link_adam -pgplot` Links an ADAM program “display' ' which uses the standard version of PGPLOT for graphical output. alink plotit.o -L. -L/star/lib `ast_link_adam -grf` -lgrf Links an ADAM program “plotit' ' , written in C. 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. alink plotit.o -L. -L/star/lib `ast_link_adam -grf_v2.0` -lgrf Links an ADAM program “plotit' ' , written in C. 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.

“-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 SystemSystem 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.