Next: Index Up: Miriad Programmers Guide Previous: Calling I/O Routines

Installation Notes

Miriad is a radio-astronomy data reduction package. It was originally
developed to meet the needs of the BIMA consortium, although ATNF is also
developing it further. It is portable to a variety of UNIX machines
as well as VMS. The notes below describe how to install it
on a UNIX machine. The distribution contains installation scripts for
SunOS, Solaris, Convex, SGI(IRIX), LINUX, OSF/Alpha, HPUX, and UNICOS.

A tar distribution of Miriad is available via three paths

Anonymous ftp: Host: ftp.atnf.csiro.au
Directory: pub/software/miriad

WWW URL: http://wwwatnf.atnf.csiro.au/Software/Analysis/miriad
Click on "Distribution,installation and update info"

On ATNF machines: Run "mirtar" yourself

FTP and WWW point to the same place, which contain both compressed
and uncompressed versions of the tar distribution file -- these tar files
contain no binaries.

The FTP and Mosaic WWW also contain the user's and programmer's guide
as separate files (these are also in the distribution). The WWW entry
contains a hypertext version of the user documentation.

Bob Sault
rsault@antf.csiro.au

========================================================================

Instructions for Installing Miriad

0) Get a copy of the Miriad distribution. If you have access to our
machines, you can generate a tar file with the desired binaries,
otherwise use the anonymous ftp or Mosaic routes.

You can create a tar backup of the Miriad environment with the command

% mirtar device binaries

where "device" is the output device or file for the tar tape, and
"binaries" can be one of: all, none or a machine time. The "binaries"
argument determines which executables and object libraries (if any)
are written to the tar tape/file.

For example

% mirtar /dev/nrst0 all

will write Miriad source and binaries for all the architectures that we
have binaries for. To see the supported architectures, use "mirtar"
without any arguments.

NOTE: Problems with operating system/compiler/shared library mismatches
can cause binaries that work on one machine NOT to run on another
very similar machine. If you take binaries -- good luck -- but it is
moderately likely that you will have to recompile anyway.

1) Untar the distribution in the target directory. The source, manuals, etc
take up about 15 Mbytes. The executables and libraries take up about 50
Mbytes on a Sun4, and 90 Mbytes on a Convex C2 (these do not use
shareable libraries).

We use the environment variable $MIR to indicate this root directory.

2) Edit $MIR/bin/MIRRC to reflect your setup. Normally it will
involve just setting the MIR environment variable:

setenv MIR miriad-root-directory

and setting up a variable to indicate the machine type

set arch = machine-architecture

It assumes the C-shell, but if you use another shell, it is a simple
job to develop your own script. The remaining instructions assume
the C-shell.

3) In your .login file, add the lines

source miriad-root-directory/bin/MIRRC
set path = ($MIRBIN $path)

to make sure your get the appropriate Miriad definitions whenever
you log in. In the above "miriad-root-directory" is the name of
the directory where you installed Miriad.

4) If your Miriad distribution contained executables, these will
depend on a number of shareable libraries.

On Suns, you may have older versions of the shareable libraries than
we have. In this case, any Miriad executables that you may have copied
from here are as good as useless -- you will have to recompile and relink
everything. If you do have inappropriate libraries, the run-time linker
(ld.so) will tell you as much when you go to run a task, and will
refuse to run the task for you.

Apart from the system libraries, applications which use PGPLOT will
require a PGPLOT shareable library and some X libraries.
The Miriad TV devices will depend on X libraries (see Section 13 if you
have problems with xmtv).

IT IS MODERATELY LIKELY THAT YOU WILL HAVE SOME LIBRARY MISMATCH PROBLEMS
AND SO WILL NEED TO RECOMPILE.

When running Miriad on Suns, you may need to set the LD_LIBRARY_PATH
environment variable (you might do this in MIRRC) to point to the directories where the
FORTRAN, PGPLOT and X shareable libraries live. This will depend whether
or not they are in the default library directories. For example,
if the FORTRAN library is in /usr/lang/SC1.0 (which is not searched
by default), and the PGPLOT and X libraries are in /usr/lib (which is
searched by default), you would need to perform the following

setenv LD_LIBRARY_PATH /usr/lang/SC1.0

See the man entry on "ld" for more information about shareable libraries
and setting LD_LIBRARY_PATH

5) If the executables are OK!
If your tar distribution had the executables that you wanted,
and if the shared libraries are OK, then you are
almost done -- Touch a time-stamp file to show that things are up to date:

% touch $MIRLIB/Last_update

If you do not have the executables for your particular machine, or
if you are going to be developing or recompiling Miriad code, you
will need to do some or all of the following steps as well.

6) The Structure of Miriad

We digress here to outline the structure of Miriad. Miriad consists of
a largish number of independent executables. Most executables will function
without the presence of any other parts of Miriad. If your interest in
Miriad is limited to a very small subset of tasks, these are the only
executables that you will need to compile.

The scripts that compile Miriad and keep it up to date are similarly
does not have a list of source files built into it. They work by
assuming all code in a few particular directories is to be compiled
and either added to a library, or linked into an executable. If you
do not want a particular set of tasks, simply delete them from the
tasks directory before you start to build the system (or delete
their executables afterwards if you find out later that a particular
task is not of interest).

Miriad directory structure. The current directory structure is as
follows. The contents of the first three directories are generated
from the other directories.

$MIR/bin/$ARCH Executables.
/lib/$ARCH Libraries and some time-stamp files.
/doc On-line help.

The followign directories contain the "source" from which the
system is generated.
/cat Miscellaneous tables, etc, used by tasks and
users
/spec Special-case source programs.
/* Various special-case programs.
/specdoc Special-case documentation files.
/inc A few include files.
/linpack LINPACK source code.
/pgplot PGPLOT code.
/oldpgplot Routines to use with old versions of PGPLOT.
/man Miriad manuals -- in LaTex and Postscript.
/user Users guide.
/prog Programmers guide.
/label Some labels for binders.
/scripts General scripts.
/unix Unix-specific scripts.
/sun4 Scripts specific to Sun machines running old SunOS
/sun4sol Scripts specific to Sun machines running solaris
/convex Scripts specific to Convex machines.
/sgi Scripts specific to Silicon Graphics/IRIX machines.
/unicos Scripts specific to Unicos Crays.
/alpha Scripts specific to DEC OSF/1 Alpha
/hpux Scripts specific to HP-UX machines
/linux Scripts specific to LINUX.
/vms Scripts specific to VMS.
/subs Miriad subroutines
/vms Subroutines specific to VMS.
/unix Subroutines specific to UNIX.
/alpha_linux Subroutines specific to DEC OSF/1 Alphas and
LINUX.
/convex Subroutines specific to Convex UNIX.
/unicos Subroutines specific to Unicos UNIX.
/hpux Subroutines specific to HP-UX.
/sgi Subroutines specific to Silicon Graphics.
/bsdvax Subroutines specific to a VAX under BSD Unix.
/prog Miriad tasks.
/tools Additional tools, in C.

Most of Miriad code is written in fairly standard Fortran-77 and C.
Miriad, however, uses both a FORTRAN and C preprocessor to add some
simple language extensions and to aid portability.

The FORTRAN preprocessor, ratty, needs to be applied to all .for files.
The FORTRAN extensions are to make some VAX extensions universally
available, to provide conditional compilation directives (little
used) and machine-independent compiler optimisation directives. The
output of ratty generally changes very little from the input, and looks
like fairly vanilla FORTRAN (with a few VAX extensions).

The C preprocessor, intf2c (which is in addition to the normal C
preprocessor) needs to be applied to all .f2c files. Passing standard
C through it simple prepends a few lines. Intf2c's only use
is to aid in the calling of C from FORTRAN. A special syntax is used
for function declarations and their dummy arguments, when these functions
are to be called by FORTRAN.

See the preamble comments of ratty.c and intf2c.c for more information.

Mirad, at one time or another, has run on (in decreasing order of our
familiarity with these installations)
Sun (SunOS and Solaris)
Convex
Silicon Graphics (SGI)
HP-UX
DEC OSF/1 Alpha
LINUX
VMS
Unicos (XMP, Cray-2 and YMP)
Multiflow
Alliant
BSD-Vax
Changes resulting from a drift towards POSIX/ANSI C compliance might
mean that Miriad will not compile immediately on some of the machines
at the bottom of the above list -- changes in the lower
level routines (mainly i/o, etc) might be needed.

With a modest amount of work, you should be able to get Miriad to
run on any supposedly POSIX complient (or nearly complient) machine.

7) If your distribution contained binaries but a rebuild is necessary
anyway, then its best to start with a clean slate. Delete all the
binaries that are bad ...

% rm $MIRLIB/* $MIRBIN/*

8) Copying and modifying scripts.
Miriad is build and updated using one C program (newer - source in the
directory $MIR/tools) and four C-shell scripts (mirupdate, mircadd, mirclnk,
mirlibs -- source in $MIR/scripts/unix/xx, where xx is a machine type
name). You may need to modify these. Often the supplied versions of
mirupdate, mircadd and mirclnk should be adequate (but mirlibs -- discussed
below -- will almost certainly not be).

* If you are using Convex, Sun, Alpha OSF, HP-UX or UNICOS operating
systems, you should not have to modify the "mircadd" or "mirclnk" scripts.
However they are NOT automatically copied to $MIRBIN, so you will need
to do this by hand. First you will need to create the binary directory.
e.g.

% cd $MIR/scripts/unix/xx
% mkdir $MIRBIN
% cp mircadd.csh $MIRBIN/mircadd
% cp mirclnk.csh $MIRBIN/mirclnk

"mircadd" compiles a C or FORTRAN subroutine and adds it to the
$MIRLIB/libmir.a library. "mirclnk" compiles and links a C or FORTRAN
program, or moves a shell script or document file. In the case
of FORTRAN code, mircadd and mirclnk also run the code through the "ratty"
preprocessor first (the ratty preprocessor, $MIR/tools/ratty.c, is
automatically compiled and copied to the $MIRBIN directory).
You may wish to modify the compiler switch settings, etc.
Once you have modified "mircadd" and "mirclnk", you must copy them to the
$MIRBIN directory.

* Like "mircadd" and "mirclnk", you will probably not need to modify the
"mirupdate" script. But you MUST copy it to the $MIRBIN directory

% cd $MIR/scripts/unix/xx
% cp mirupdate.csh $MIRBIN/mirupdate

The "mirupdate" script looks for source files which are out of date
(using newer), and invokes "mircadd" and "mirclnk" to do the updating.
The heart of "mirupdate" looks something like:

doscripts $MIR/scripts/unix{/sun4,}
dosubs $MIR/subs{/unix/sun4,/unix,} $MIR/linpack
dotools $MIR/tools
doprog $MIR/prog
dodocs $MIR/specdoc

(check on using curly brackets, {}, in the C-shell if you are not
familiar with this syntax). Each line consists of a "do" command which
searches a list of directories for modified source files. It searches
the directories in order, and if multiple files with the same name
are found, the one found first is the one that takes precedence. So
you place the more machine-specific directories earliest in the list.
This way if you have a machine-specific version of some code (e.g.
optimised for your machine, or calls the appropriate system services),
it will be used rather than the more generic version.
Modify the search lists to your particular needs.

9) Link libraries and mirlibs.

The way that you tell the Miriad compile/link scripts what
libraries to use when linking (and where these libraries are) is done by
a trivial script -- "mirlibs"

"mirlibs" is a one-line script, which echos the libraries needed to
link a Miriad task. It is the ONE and ONLY place where the link
libraries are mentioned in Miriad's installation scripts. You must
set this so that tasks can be linked correctly. Typical usage of
the mirlibs command (within mirclnk) is

f77 -o $MIRBIN/task task.f `mirlibs`

Typically mirlibs will look something like

#!/bin/csh
echo $MIRLIB/libmir.a -lpgplot -lm -lX11

which indicates that the Miriad library (libmir.a), plus the PGPLOT
library and some libraries needed by PGPLOT.

All flags, etc, appropriate for the linker can be used in
mirlibs. As well as a list of libraries, mirlibs may, for example, include
the -L switch to indicate a directory to search for libraries.

The libraries that Miriad depends on include:

* The most obvious library is $MIRLIB/libmir.a -- the Miriad subroutine
library. Include this in mirlibs.

* The PGPLOT plotting library is used by a significant number of tasks.
Miriad requires PGPLOT version 5.0 or later.
You should install that first, and set the necessary environment
variables to use PGPLOT -- if needed. See the installation notes that
come with PGPLOT.

Depending on your setup, PGPLOT may depend on other libraries (e.g.
Sunview and X11 libraries). You will need to include these in mirlibs.

PGPLOT is available via anonymous ftp from astro.caltech.edu
(131.215.240.1). The subdirectory "pub/pgplot" contains the file
pgplot5.0.tar.Z -- which is a compressed tar file. Tim Pearson
(tjp@astro.caltech.edu) can give advice on installing PGPLOT.

The tar distribution for Miriad also comes with this distribution,
(subdirectory pgplot). However if you already have a copy, you may
choose to delete the Miriad copy -- BUT READ BELOW.

PGPLOT was comparatively recently changed to conform to the FORTRAN-77
restriction that names should not exceed 6 characters, as well as
fixing a number of bugs that affect Miriad tasks. We encourage you
to make sure that you have an up-to-date version of PGPLOT.

If you have an old version of PGPLOT (prior to version 5.0), and are
not inclined to update it, you are not completely lost, but you will
have to forget about the cg*.for tasks, and live with some PGPLOT
bugs in other tasks. Some of the relatively recent changes to PGPLOT
required renaming a number of routines, without affecting their
functionality. Miriad uses the new subroutine names. If you want to
live with an "old" version, you can include the FORTRAN file in the
directory oldpgplot in the Miriad library. Include the compiling of
this in the normal Miriad updating script. NOTE you should do this ONLY
if you have an "old" version of PGPLOT. The simplest way to check
whether your version is "old" is to check whether the routine PGBEG
exists. If not, its old.

* The ATLOD task (and only ATLOD) uses the ATNF RPFITS library.
The installation scripts do not build or install the RPFITS library.
If you want the ATLOD task, you will have to install the RPFITS
library by hand. The Miriad distribution comes with only the
binary library for the RPFITS library. To install this

% cd $MIR/rpfits
% cp rpfits.inc $MIRINC
% cd $ARCH
% cp librpfits.a $MIRLIB
% ranlib $MIRLIB/librpfits.a (this is not required on some systems)

and edit mirlibs.csh to echo $MIRLIB/librpfits.a

If you are uninterested in ATLOD or RPFITS, you may delete them.

If the binary libraries (as shipped) are not adequate for your
system, source code are available from
ftp://atnf.csiro.au/pub/software/rpfits. Installing it should be
straighforward. Advice is available from Henrietta May
(hmay@atnf.csiro.au).

* A number of tasks use the LINPACK library. An optimised version of
this library comes with a number of high performance machines (veclib on
Convexs, scilib on Unicos, complib.sgimath on SGI), or you may have
a local copy (either LINPACK or LAPACK). The source code is also
included in the Miriad distribution. If you have a better version of
LINPACK, delete the Miriad version. Otherwise, you can include the
compiling of the LINPACK library in the normal Miriad updating scripts.

In summary:
Edit mirlibs to reflect the needed libraries.

% cd $MIR/scripts/unix/xx
% vi mirlibs.csh

The mirupdate scripts automatically copies mirlibs to the $MIRBIN directory
after it has been modified.

10) Compiling the "newer" program:
The "newer" command needs to be compiled by hand, and the result
stored in $MIRBIN. For example

% cc -Dposix -o $MIRBIN/newer $MIR/tools/newer.c

Ignore any message you get about posix being redefined.
The -D switch indicates that you machine uses the POSIX-style directory
i/o routines (Newer contains the code for a number of possibilities
other than POSIX -- see the preamble comments).

11) Customizing the Problem Size
The include file, $MIRINC/maxdim.h, gives some parameters which
set the maximum sized problems that Miriad can cope with. Increase
the values set here if your site needs to work with bigger problems.
Decrease the values if you are short of swap space or memory. No
code allocate memory which is more that a few times any of the
parameters in the maxdim.h file (i.e. there are no arrays of size
MAXDIM**2, MAXDIM being the maximum dimension of an image). Miriad
programs generally dynamically allocate memory when needed.

Some exceptions are tasks that use the include file $MIRINC/tmpdim.h
This is similar to maxdim.h, except the values are invariably set
to smaller numbers. This is as programs which use this include file
do statically declare arrays of size MAXDIM**2 or similar.

In summary, you may wish to edit the parameter settings in maxdim.h
and tmpdim.h to reflect your problem sizes and memory availability.

12) Summary: Building or Updating the Bulk of Miriad

You should have
Modified if needed: mirlibs,mircadd,mirclnk,mirupdate
Copied to $MIRBIN: mircadd,mirclnk,mirupdate
Compiled into $MIRBIN: newer
Setup the environment variables in MIRRC
Included $MIRBIN in your path -- rehash to make sure your path
is up-to-date.

At this stage, typing

% mirupdate

should cause all modified files to be recompiled and rebuilt. Invoking
it the first time will take a good deal of time to recompile everything.
Unfortunately the script does not recover from errors. If it fails, you
will have to start recompiling things from scratch!!

When it finishes, it will prompt to ask whether to record the update
time -- answer "y" for yes (otherwise it will not believe that it has
successfully compiled everything. Subsequent invocations will only
recompile files that have been modified.

13) Trouble shooting.
If "mirupdate" successfully finishes compiling the subroutines, but starts
to fail to link the tasks, interrupt it! At this stage try to compile
and link a task by hand. e.g. to compile prthd, use

% fortran -o $MIRBIN/prthd prthd.for `mirlibs`

When you have sorted out the problem (perhaps mirlibs was inappropriate)
use the following commands to proceed without having to start from scratch:

% touch $MIRLIB/Last_update
% touch $MIR/prog/*
% mirupdate

This causes the time-stamp file (Last_update) to be more recently
modified than the subroutines, but the programs appear to have
been modified even more recently.

14) Special cases!
Unfortunately there are a number of special cases. Most of them have
Build files to be used. All these special cases exist in subdirectories of
$MIR/spec. You might have to adapt the Build files for your local set-up.
They generally leave the executable in the local directory, which you
then have to copy by hand into the $MIRBIN directory (xmtv and sxmtv
are exceptions).

* miriad: The "miriad" ($MIR/tools/miriad.c) front-end can use the
GNU READLINE library to allow command line editting. This is
very useful. The normal installation does not require the
READLINE library (and does not have line editting). If you have a
copy of the READLINE library (or you can get it, via anonymous ftp,
from ftp://prep.ai.mit.edu/pub/gnu/readline-2.0.tar.gz -- which
is a GNU zipped tar file) you can use the Build script in
$MIR/spec/miriad to generate miriad.c using the READLINE library.

* xmtv: An X-based TV server. Requires the Athena Widgets (libXaw)
X library, as well as the normal(?) X libraries Xmu, Xext, Xt and X11.
These must be revision 5 at least. If you do not have Athena
Widgets or revision 5, the binary Miriad distributions include a
statically linked version of xmtv for some systems. Even if
would have to recompile all the other binaries because of shared
library problems, the statically linked version should still work.
You should not need to do anything special for it.

* sxmtv: A simple version of xmtv. Requires only X11 library, and
works on a greater range of platforms and X versions. See the
README file in the sxmtv directory for more info.

* xpanel: An X Windows "control panel", used by TVFLAG and TVCLN.
It requires Athena widgets.

* emacs: Actually microEmacs, my (rjs) preferred editor. Its included in
case I need to log into this account.

========================================================================

Getting Regular Updates

Having installed a current version of Miriad, you can readily keep this
up-to-date. We use a weekly schedule of distributing updates (updates
are generated by 10:15 pm Sydney time on Thursday evenings). We
assume that you already have a current version of Miriad.

The update starts with an ATNF machine generating an update
tar file in its anonymous FTP area. Then a job on your machine picks
up this update and installing it. The process of picking up the update
leaves behind a acknowledgement file, so that the ATNF machine can
delete updates that have already been retrieved.

If an update is missed for some reason, then it will be picked
up the next time around.

To get regular updates:

1) Tell Bob Sault (rsault@atnf.csiro.au) that you wish to have
updates generated, and give him a "site-name". For example, the
site name for the University of Melbourne Astronomy group might
be "UniMelb" (case sensitive).

2) Create a directory $MIR/import

% mkdir $MIR/import

3) Schedule a cron job to run after the update is generated at ATNF. The
cron job should:
* Set up its environment so that the Miriad executables are in
its path, and that the Miriad environment variables are defined.
* Execute the c-shell script.
mirimport site-name
For example, the crontab table at the University of Melbourne would look
like

30 22 * * 4 csh%source /miriad/bin/MIRRC%set path = ($MIRBIN $path)%mirimport UniMelb

This runs at 10:30 pm on Thursdays, uses the c-shell, sets the Miriad
environment, and runs mirimport.

Although the update process is conveniently down automatically, it can
also be done by hand. The command

% mirexport UniMelb

on an ATNF machine will generate an update for the University of Melbourne,
and then

% mirimport UniMelb

on a University of Melbourne machine will retrieve it.

Last generated by rsault@atnf.csiro.au on 14 Mar 1996