Distributed in the Astro build. Access by:

Activate starlink

This will source the appropriate startup files into your current shell, which in turn will set a multitude of environment variables and aliases.

It will also announce which version of Starlink is being Activated, by saying something of the form:

Using Starlink hikianalia (2013-April-12)

.... at Activation time. Versions which are installed within Astrophysics include:

  • kapuahi: Installed on most systems; available for installation from Self-Service, for those who wish to update their own systems at a time of their choosing.
    • Please check first before blindly installing it:

      Activate installed starlink

  • hikianalia: Announced on 16th April 2013 as a full release.
    • This is now available for intrepid testers from Self-Service. Please send us your plaudits and horror stories.
  • nanahope: Frankly obsolete. Still present on some Snow Leopard systems at the time of writing (April 2013).

It's possible to have multiple versions on the same system, and select one at will. To see what's been installed on your system, say either of the following at a shell prompt:

Activate installed starlink
Activate starlink --available

(You don't need to have Activated Starlink first.) The default will be the first version listed. If you wish to Activate an older installed version, say (in a fresh shell) something of the form:

Activate starlink kapuahi



Activate help starlink
Activate help starlink kapuahi # Specify release
Activate help starlink | less  # Page the result

.... at the command line. (You don't need to have Activated any version of Starlink first.)


If you wish to link one or more of the Starlink libraries into your own software, Activate the appropriate version of Starlink, then add the following command-line option to your compiler, to tell it where the libraries live:


(no space after the capital L), and see below for how to specify the libraries. To find C (or F90) header files, use also:

-I $/include

(including the space after the capital I). These will work both in shellfiles and at the command line (where the curly braces will help), and also in Makefiles (where they're a valid alternative to the otherwise-mandatory parentheses): the shell code (resp: make) will import the value of the environment variable ${STARLINK_DIR} from your current shell's environment without further ado.

The "-L" option above above is necessary, but not sufficient at build time: linking in libraries is not trivial when they depend on other libraries. To simplify this, Starlink provides shortcuts for the necessary and sufficient set of libraries into the compiler command, using the "backquotes" shell mechanism (explained in the collapsed section below) to insert them into the executed command. This saves you having to know what the full necessary set of library statements may happen to be, and would track any differences in said set in updated versions of Starlink (or under other operating systems) without needing your intervention.

Explanation of "backquotes mechanism"

This is used in the Starlink collection to group together potentially long and complicated link-time sets of arguments. For example, if you give the command

foo `bar_link`

to the shell, it runs the program bar_link for itself, collects the output thereof (say -lbar -lbaz), replaces the backquoted section of the command you first thought of by said output, and then runs that. In this example, the shell therefore ends up actually running the command

foo -lbar -lbaz

This relieves you of the burden of having to know quite which libraries depend on which others (Starlink and/or system), and of having to adjust your compiler incantations when (not if) they change with future Starlink or system updates. Think of it as active documentation: the underlying reality may change, but the user-level usage won't.

Example usages include:

Activate starlink # .... once per shell

gfortran -o foo foo.o bar.o baz.o \
-L$STARLINK_DIR/lib `cfitsio_link`

gfortran -o foo foo.o bar.o baz.o \
-L$STARLINK_DIR/lib `pgplot_link`

gcc -I $STARLINK_DIR/include -c foo.c
g++ -I $STARLINK_DIR/include -c
gfortran -o foo foo.o bar.o baz.o \
-lcpgplot `pgplot_link`

g++ -I $STARLINK_DIR/include -c
gfortran -o foo foo.o tkbar.o baz.o \
-ltkpgplot -ltk8.5 -ltcl8.5 \
-lcpgplot `pgplot_link`

(NB: each of the gfortran lines has been split with one or more backslashes, as they would otherwise be too long to fit in this margin.) As usual, order of libraries is significant: -lcpgplot and/or -ltkpgplot needs to appear before the -lpgplot which is inside the `pgplot_link` phrase. This is particularly pernicious in the case of libtkpgplot --- the compilation appears to succeed, but the resultant executable will fail to understand the /xtk output device type.

Please note: You will need to use gfortran to link with libcpgplot, even if all your own code is in C and/or C++. The main PGPLOT library is written in Fortran, and (at least under MacOS X) libpgplot and gfortran use multiple Fortran-specific and compiler-specific libraries between them. Please see Where has g77 gone to? for a fuller discussion; in the meantime, new code should use PLPLOT instead, as this is being actively maintained, and is understood to be more C-friendly.

Please see Environment Variables in Astrophysics: Libraries, on why using environment variables is usually superior to stitching long absolute pathnames (which are subject to change) into shell scripts or Makefiles, and is quite definitely superior to typing in said long pathnames by hand every time.

Historical Notes

Extremely briefly: The Starlink Project (which supplied hardware and support to UK universities) is no more, but the Starlink software lives on, and is currently hosted by the Joint Astronomy Centre in Hawaii. The status of the software is somewhere between "under development" and "under very active maintenance", as it is in active daily use at JACH and elsewhere, and because circumstances and instruments do keep changing so.

For more information, please see:

Categories: Apple | Astro software | Astrophysics | Development | Mac | OS X