                   CFITSIO Interface Library

CFITSIO is a library of ANSI C routines for reading and writing FITS
format data files.  A set of Fortran-callable wrapper routines are also
included for the convenience of Fortran programmers.  This README file
gives a brief summary of how to build and test CFITSIO, but the CFITSIO
User's Guide, found in the files cfitsio.doc (plain text), cfitsio.tex
(LaTeX source file), or cfitsio.ps (postscript format), should be
referenced for the latest and most complete information.

BUILDING CFITSIO
----------------

The CFITSIO code is contained in about 40 *.c source files and several *.h
header files.  The CFITSIO library is built on Unix systems by typing:

>  ./configure
>  make

at the operating system prompt.  The 'configure' command customizes
the Makefile for your particular system, then the 'make' command
builds the library.

On VAX/VMS and ALPHA/VMS systems the make.com command file may be used
to build the cfitsio.olb object library using the default G-floating
point option for double variables.  The make\_dfloat.com and make\_ieee.com
files may be used instead to build the library with the other floating
point options.

A precompiled DLL version of CFITSIO is available for IBM-PC users of
the Borland or Microsoft Visual C++ compilers in the files
cfitsiodll_2xxx_borland.zip and cfitsiodll_2xxx_vcc.zip, where '2xxx'
represents the current release number.  These zip archives also
contains other files and instructions on how to use the CFITSIO DLL
library. The CFITSIO library may also be built from the source code
using the makefile.bc or makefile.vcc  files.  Finally, the makepc.bat
file gives an example of  building CFITSIO with the Borland C++ v4.5
compiler using simpler DOS commands.

On OS/2 systems, CFITSIO can be built using the supplied makefile by
typing 'make -f makefile.os2'.  This makefile requires the GCC compiler
and EMX library, which are available from many Internet sites
containing OS/2 software, such as
ftp-os2.nmsu.edu/pub/os2/dev/emx/v0.9c and
ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc.

The MacOS version of the cfitsio library can be built by (1) un binhex
and unstuff cfitsio_mac.sit.hqx, (2) put CFitsioPPC.mcp in the cfitsio
directory, and (3) load CFitsioPPC.mcp into CodeWarrior Pro 5 and
make.  This builds the cfitsio library for PPC.  There are also targets
for both the test program and the speed test program.

To use the MacOS port you can add Cfitsio PPC.lib to your Codewarrior
Pro 5 project.  Note that this only has been tested for the PPC and
probably won't work
 on 68k macs.

TESTING CFITSIO
---------------

The CFITSIO library should be tested by building and running
the testprog.c program that is included with the release. 
On Unix systems, type:
-
    % make testprog
    % testprog > testprog.lis
    % diff testprog.lis testprog.out
    % cmp testprog.fit testprog.std
-
 On VMS systems,
(assuming cc is the name of the C compiler command), type:
-
    $ cc testprog.c
    $ link testprog, cfitsio/lib
    $ run testprog
-
The testprog program should produce a FITS file called `testprog.fit'
that is identical to the testprog.std FITS file included in this
release.  The diagnostic messages (which were piped to the file
testprog.lis in the Unix example) should be identical to the listing
contained in the file testprog.out.  The 'diff' and 'cmp' commands
shown above should not report any differences in the files.

USING CFITSIO
-------------

The CFITSIO User's Guide, contained in the files cfitsio.doc (plain
text file) and cfitsio.ps (postscript file), provides detailed
documentation about how to build and use the CFITSIO library.
It contains a description of every user-callable routine in the
CFITSIO interface.

The cookbook.c file provides some sample routines for performing common
operations on various types of FITS files.  Programmers are urged to
examine these routines for recommended programming practices when using
CFITSIO.  Users are free to copy or modify these routines for their own
purposes.

SUPPORTED PLATFORMS
-------------------

CFITSIO has currently been tested on the following platforms:

   Operating System          Compiler
   ----------------          --------
  OPERATING SYSTEM           COMPILER
   Sun OS                     gcc and cc (3.0.1)
   Sun Solaris                gcc and cc
   Silicon Graphics IRIX      gcc and cc
   Silicon Graphics IRIX64    MIPS
   Dec Alpha OSF/1            gcc and cc
   DECstation  Ultrix         gcc
   Dec Alpha OpenVMS          cc 
   DEC VAX/VMS                gcc and cc
   HP-UX                      gcc
   IBM AIX                    gcc
   Linux                      gcc
   MkLinux                    DR3
   Windows 95/98/NT           Borland C++ V4.5
   Windows 95/98/NT           Microsoft/Compaq Visual C++ v5.0, v6.0
   Windows 95/98/NT           Cygwin gcc
   OS/2                       gcc + EMX
   MacOS 7.1 or greater       Metrowerks 10.+

CFITSIO will probably run on most other Unix platforms without
modification.  Cray supercomputers and IBM mainframe computers are
currently not supported.

Reports of any success or failure to run CFITSIO on other platforms
would be appreciated.  Any problem reports or suggestions for
improvements are also welcome and should be sent to the primary author.

-------------------------------------------------------------------------
William D. Pence
pence@tetra.gsfc.nasa.gov
HEASARC, NASA/GSFC
