Click on the image for a larger view

Overview

This tutorial shows you how to install the SuperDARN Toolkit on MacOS X. Although MacOS X is a UNIX based Operating System, it has a number of subtle differences that complicate the installation process.

This tutorial assumes that you are installing on MacOS X 10.3 (Panther).

When you have completed the installation, you will have a fully functioning SuperDARN Data Analysis toolkit.

Preparing MacOS X

Installing X11 for MacOS X

The first step is to install the X11 for MacOS X, this can be found either on the Operating System installation disks or on the Apple web site here. The X11 software is required by both the SuperDARN software toolkit and by IDL.

The next step is to install the MacOS X software developement tools, called Xcode. This software includes the gcc compiler and gnumake programs that are needed to compile the code. They can be obtained from Apple by registering as an Apple developer, here. When you install the development tools, make sure you include the package for X11 development.

Installing IDL 6.x

If you intend to use the software toolkit from IDL, you must install IDL on your machine. The code has been tested against IDL 6.0 and IDL 6.1. The default installation directory has been changed for IDL 6.1, IDL is now installed under the Applications directory and not /usr/local. In this tutorial it is assumed that you are using IDL 6.1, the pathnames will have to modified accordingly if you are using IDL 6.0. You can download IDL from RSI.

CDF Software

If you intend to work with data from NSSDC you will need to install the Common Data Format software distribution from here. They have a self-installing archive and full instructions on how to install the software.

Other Software

One of the most useful software packages comes from the Fink project. This is a package management system for installing a variety of Open Source UNIX software on MacOS X. Packages are included for emacs21, netpbm, and netcdf, as well as a host of other software. You can download Fink from here.

Installing the Toolkit

Installing the Core Softare

First you must download the core rst software from the SuperDARN web-site and copy it to your home directory. The software is stored in the form of a self-extracting archive that you can install by typing:

chmod +x core.darwin.x.yy.sh
./core.darwin.x.yy.sh

This should compile the core software and install it in your home directory.

Updating the User Profile for the Core Software

The next step is to modify your default profile, to include the necessary environment variables for compiling code. By default, MacOS X 10.3 uses the bash shell, and the user profile is stored in the file .profile. If you are running bash add the following two lines to .profile:

export OSTYPE="darwin"
export HOMEPATH="${HOME}"

Older versions of MacOS X used the tcsh which stores the user profile in .cshrc. If you are running the tcsh, add the following lines to .cshrc:

setenv OSTYPE "linux"
setenv HOMEPATH "${HOME}"

The next step is to incorporate the environment variables defined in the file profile.core.bash (profile.core.tcsh, for tcsh users). You can either do this by cutting and pasting the contents of the file into the default profile, which is probably the best option, or by referencing the file in your profile by adding one extra line. If you are running bash, add the following line to .profile:

. $HOME/profile.core.bash

If you are running tcsh add the following line to .tcsh:

source $HOME/profile.core.tcsh

Next you must refresh you profile. If you are a running bash, type:

. .profile

If you are running tcsh, type:

source .cshrc

Alternatively, you can update the profile by closing the terminal window and opening a new one.

Installing the Toolkit package

The next step is to install the SuperDARN Toolkit package by typing:

rpkg superdarn-toolkit.x.yy.rpkg

This should unpack the source code, data tables, scripts, and headers and place them in the correct directories. It should also place to files containing the environment variables for the toolkit in your home directory.

Adjusting the Environment Variables

You will need to make a few changes to these variables to deal with the differences between MacOS X and other versions of UNIX.If you are running bash you will need to edit profile.superdarn-toolkit.bash, if you are running tcsh you will need to edit profile.superdarn-toolkit.tcsh.

Look through the file for the section entitled "Compilation Directives".

X11

If you have installed the X11 development libraries and wish to use them, change the environment variable XPATH to point to the directory that X11 has been installed in, this is usually /usr/X11R6. If you don't want to use the X11 libraries, then comment out this environment variable by putting a "#" character at the start of the line.

netcdf

If you have installed the netcdf software and wish to use it, uncomment the environment variable NETCDF by removing the leading "#" character from the start of the line. You must also change the environment variable to point to the directory that netcdf has been installed in, if you installed this using fink this directory is usually /sw.

CDF

If you have installed the CDF software and wish to use it, change the environment variable CDF_PATH to point to the directory that the CDF distribution has been installed in, this is usually $HOME/cdfXX-dist. If you don't want to use the CDF software, then comment out this environment variable by putting a "#" character at the start of the line.

IDL

The next change is to modify the environment variable IDL_IPATH to point to the directory containing the header files needs to compile the IDL interface libraries.

If you have installed IDL 6.1, then this directory is most likely to be /Applications/rsi/idl/external/include.

If you have installed IDL 6.0, then the directory is most likely to be /usr/local/rsi/idl/external/include.

You must next make some changes to the IDL runtime environment, look through the file for the section entitled "IDL Configuration"

The environment variable IDL_PATH is used to define the search path IDL uses when looking for library files. As IDL 6.1 is installed in the /Applications directory, you will need to change the definition of this variable to "+/Applications/rsi:+/${HOMEPATH}/idl/lib". If you are using IDL 6.0 and it is installed in the directory /usr/local, then you can leave this variable unchanged.

MacOS X differs from other versions of UNIX in that the suffix applied to shared libraries (referred to as dynamic libraries) is dylib. Change the file suffix ".so" on all the environment variables that start with the prefix "LIB" to ".dylib".

Legacy Environment Variables

The final two enviroment variables that may need to be changed are SD_RAWROPEN_PATH and SD_FITROPEN_PATH. You should set them to point to the directories in which the fit and dat files will be stored.

Once you have completed modifying the profile, save it to disk.

Updating the User Profile for the SuperDARN Toolkit

The next step is to incorporate the environment variables defined in the file profile.superdarn-toolkit.bash (profile.superdarn-toolkit.tcsh, for tcsh users). As with the core software, you can either do this by cutting and pasting the contents of the file into the default profile, which is probably the best option, or by referencing the file in your profile by adding one extra line. If you are running bash, add the following line to .profile:

. $HOME/profile.superdarn-toolkit.bash

If you are running tcsh add the following line to .tcsh:

source $HOME/profile.superdarn-toolkit.tcsh

Next you must refresh your profile again. If you are a running bash, type:

. .profile

If you are running tcsh, type:

source .cshrc

Alternatively, you can update the profile by closing the terminal window and opening a new one.

Compiling the SuperDARN Toolkit

The final step of the installation process is to compile the toolkit by typing the following:

make.all

If everything is configured correctly, this should compile all of the libraries and binaries in the toolkit.