Applications Setup

Preface

You can't have everything. Where would you put it?

    -- Steven Wright

Many software suites require the user to modify environment variables, sometimes in ways which are mutually incompatible. Rather than chase the ultimately futile dream of "one size fits all", the Applications Setup approach is to instead provide simplified setup commands ("Activations") which do the modifications in question on a per-package basis, and which can be used at the prompt of your current shell as and when needed. Thus, "Activate this" will customise one's general-purpose shell environment to use this package, without the customisations required by that package getting underfoot.

There are also help and search facilities, to help discover which programs and libraries are in which package or suite, and vice versa.

PLEASE NOTE: We are in the process of eliminating the need for Activation. Please try whatever you're after doing first without Activating anything .... you may be pleasantly surprised.

Please see also (in no particular order):

Executive Summary

  • Put this in your .cshrc, then start a fresh shell. Please note that "Setup" has a capital S, but "source" doesn't.

    source /Local/bin/Setup.csh

    • This should already be present.

  • To check whether (say) Starlink is installed, without Activating it:

    Activate installed starlink

  • To Activate (say) Starlink. This needs to be done once per shell (see below).

    Activate starlink

    • Do NOT put any Activation in your shell startup files.

  • To check what's there in (say) Starlink. Please note that this is rather long: see below for how to page this through less, or save it to a file.

    Activate help starlink

  • To see whether (say) GNUplot is present on your system, and whether a "wrapper script" is available.

    Activate search gnuplot

  • If you encounter problems, read on ....

Setup and Usage

Initial Setting Up

Add to your .cshrc (note the upper-case S):

source /Local/bin/Setup.csh

Then restart the shell (terminal or xterm, to taste), or start another one. This will add an alias called Activate to your running shell, which can then be used to invoke initialisation shims (which live in /Local/bin/init) on an as-needed basis, as shown below. Remember:

  • The additional line in your .cshrc is done once for all time.
  • Each Activate command is used once per shell.

If you use bash instead of tcsh, you should instead add to your .bashrc:

. /Local/bin/Setup.bash

(including the initial dot, which is how Bourne shells pronounce "source"). This will have exactly similar results to the tcsh version, except (for us pedants) that Activate is a shell function, rather than an alias which sources an external script to do its dirty work. You will also need to ensure that your .bash_profile (or .profile) contains something along the following lines:

if [ -r $HOME/.bashrc ] ; then
  . $HOME/.bashrc
fi

(don't forget the dot in the middle line). This will make assurance double sure that the contents of .bashrc will be acted upon whenever bash is invoked as a "login shell".

Test the Setup mechanism:

Activate foo

This says "foo" at the prompt; adds a shell variable called "foo", and an environment variable called "bar", to your running shell; and tells you what it's done. Check the results for yourself with

set | grep -i foo
printenv | grep -i foo

This test and demo may mutate, but probably won't disappear altogether.

Usage

To Activate (eg) the Starlink collection, say at your command prompt:

Activate starlink

This will set up your $PATH, alter certain environment variables (often $DYLD_LIBRARY_PATH and co-conspirators), and/or add certain aliases, in order to make the Activated suite or program available to you in your current shell. De-Activating a program or suite is as simple as starting up a new shell, and working in that instead. Again, remember:

  • The additional line in your .cshrc is done once for all time.
  • Each Activate command is used once per shell.

If you wish to use one particular set of commands frequently, put them in a file, and "source" that file on a need-to-use basis.

Testing for availability:

To see whether something could be Activated, but without actually doing so, say (for example):

Activate installed starlink

This runs installed_test.sh in a subshell, does the Activation of (in this case) Starlink within that, and reports the results; basically, it shows what doing the Activation in your current shell would do, but without disturbing your current shell's environment. This is useful for determining whether some optional software has or has not been installed from Self-Service.

As a bonus, with a select set of suites and utilities, it reports version information of whatever it finds. This currently includes SciSoft, Starlink, the Intel compilers, NAG software, and XCode Tools (see also gcctest); the list will be extended as time allows.

Possible error messages:

  • Activate: command not found

    You've forgotten to source /Local/bin/Setup.{csh,bash} by hand, or haven't restarted your shell since putting the line in the relevant startup file. (Alternatively, if you're using a laptop or other system that hasn't been connected in a while, Applications Setup may be a bit out-of-date. Please see above.)

  • prog: Command not found (where you know program prog is in package package)

    You've forgotten to say "Activate package" at the prompt of your current shell. This can be most misleading when you don't know that (eg) SuperMongo is part of Scisoft (Activate search supermongo will be your friend here).

  • Sorry: can't set up package

    Applications Setup doesn't know about package. Try using it anyway: there may be no need for an Activation.

  • *** Sorry: package not available

    Applications Setup knows about package, but it's not installed yet. Try (re)installing it from Self-Service.

  • A complaint of the form setenv: too many variables

    This suggests some pathname may have a space in it, and hasn't been quoted correctly somewhere along the line. If you've recently edited any startup files (most notoriously, .tshrc), check any aliases and environment variables you may have set therein for syntax errors of this sort.

Please note that problems of this form may not manifest themselves immediately (like a rake in the long grass, waiting to be trodden on).

Tip of the Day: when debugging this sort of thing, don't cut things out; comment them out instead. This'll save you a lot of (mis)remembering and (re)typing.

Updates and Additions:

The files which constitute the Applications Setup are distributed to all desktop systems on a weekly basis, to correct problems and to distribute functional updates. Please contact IT Support at the usual address if you need an urgent update (eg to a laptop system which has not been in contact with the Central Physics server for a while), or if you wish to suggest some new or revised Activation, or if you have spotted some inconsistency or other shortcoming in the help and search facilities.

Help and Search

The Help and Search Facilities

The Application Setup facility has "help" and "search" commands. Thus:

Activate help

gives a brief summary of all possible available packages to which Applications Setup applies;

Activate help idl

(for example) gives further information about IDL;

Activate help gnuplot

will find and document (on an Astro system) two different versions of GNUplot, plus a command-line wrapper script which avoids certain problems with the executables without disturbing your current shell environment; and, also for viewers in Astrophysics,

Activate help macports
Activate help scisoft
Activate help starlink

additionally list the manifests for the respective suites, including version information. (Manifests are also available for AstrOmatic, and the Python Astropack, but only if you've installed them.)

Since some of these yield copious output, piping the output of Activate help into some other program will be useful. Thus,

Activate help | less

will permit you to page through the list, and

Activate help starlink | a2ps

would send a paginated version of the Starlink helpfile and manifest to your default printer.

The Search and Help facilities have now been merged, and made more verbose; the chief difference now is whether to give a summary, or the full help info (plus manifests for suites). Thus,

Activate help gsl
Activate search gsl

will both show you that MacPorts, Scisoft and Starlink all sport instances of the GNU Scientific Library, in three different versions. (As it happens, SciSoft's instance is gsl-1.14, not 2.14 as alleged in its manifest file. Moral: measure twice, cut once.)

Searching in greater depth

Activate help foo or Activate search foo does a whole-word match a la Google (or grep -iw). If you wish to match part of a word, try something of the form:

Activate help scisoft | grep -i gsl

This will show you that Scisoft has PyGSL present, as well as GSL.

Beware of attempting to use this to seek excessively short strings:

Activate help scisoft | grep -i c

matched 38% of the known universe (at the time of writing) without finding a single C compiler. On the other hand,

Activate help scisoft | grep -i sci

will find both ScientificPython and scipy (though you might have to look harder). I understand these are different things.

Footnotes

Alison Crocker's script example

The following (slightly edited) script has been used in real life [Alison Crocker, semi-pri comm]; it demonstrates what should be done, and manages to mostly avoid what shouldn't (I liked it so much that I stole it, and made it the basis of many of the wrapper scripts in /Local/bin). I presume the script in question is in a file on her path, and has been rendered executable --- "man chmod" will be your friend.

I just type 'iraf' now in a terminal and it works, just tested to be sure. When I do that, the following script is called (starting ds9 is superfluous, obviously):

#!/bin/tcsh
source /Local/bin/Setup.csh
Activate iraf
cd $HOME/iraf/
ds9 &
xgterm -fn 9x15 -sb -e ecl &
exit 0

Hope that helps!
Ali

Another example: using an alias

Here's an example of how to use an alias to do an Activation and launch an application in one go, all in the current shell. This is tcsh-specific; translation to bash is left as an exercise (extra marks for putting it all in a self-destroying shell function).

WARNING: This trick will fail dramatically if the Activation causes an alias to be defined, rather than putting the executable in question on your $PATH. Known offenders include IDL (as of at least version 8.1), and much of the Starlink software.

The application in this example is SuperMongo, which was at the time of writing part of the SciSoft suite (available in all good Astrophysics installations). The burden of this example has now been put in a wrapper script, so this example is largely of historical and educational interest.

Normally, one would have done

Activate scisoft
sm

to invoke it. To save having to remember to do the first step, create a file called ".sm_launch.csh" in your home directory, with the following contents:

source /Local/bin/Setup.csh # .... if not already in your .cshrc
Activate scisoft # Do relevant Hack
unalias sm # Cut out the middleman (see below)
\sm "$*" # Pass on command-line args to SuperMongo

Then put the following line in your .cshrc:

alias sm 'source $HOME/.sm_launch.csh '

Now watch it in action:

  • User says "sm" at the command line.
    • The alias sources the setup file into the current shell, in case User's forgotten (or carefully neglected) to put that in .cshrc as well.
    • The Activation is performed in the current shell. In particular, the SuperMongo program is put on the $PATH.
    • The script blows the alias away in the current shell, but itself continues to execute.
    • The SuperMongo program itself is invoked.
  • User exits from SuperMongo in due course, at which point the script also exits.
  • Somewhat later, User says "sm" again at the command line in the same shell.
    • The alias is no longer in place, but SuperMongo program is now on the $PATH in that shell, so the system directly invokes the SuperMongo executable.

The "unalias" line is doubly important:

  • The Activation need only be done once for your current shell. Activating the same thing more than once would at best needlessly extend your path and other environment variables.
    • Certain Activations would be broken by attempts to do them more than once. In particular, SciSoft now point-blank refuses if you attempt to reActivate it.
  • There's the danger that the last line would recursively activate the same alias, with (ahem) hilarious consequences. Adding the leading backslash should also prevent this, but I'm a believer in belt-and-braces.

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