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 latest
and most complete information may be found in the "docs" folder in the
CFITSIO User's Guide:

  For C programmers:

   cfitsio.tex (LaTeX source file)
   cfitsio.ps  (PostScript file)
   cfitsio.pdf (Portable Document Format)

  For Fortran programmers:

   fitsio.tex (LaTeX source file)
   fitsio.ps  (PostScript file)
   fitsio.pdf (Portable Document Format)

  Quick Start guide:

   quick.tex (LaTeX source file)
   quick.ps  (PostScript file)
   quick.pdf (Portable Document Format)

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

The CFITSIO code (contained in *.c source files and several *.h
header files) should compile and run on most Unix platforms without
modification.  The standard way to build the library on Unix systems
is the usual GNU-like approach, i.e. by first typing

 % ./configure  [--prefix=/target/installation/path]

at the operating system prompt.  Type './configure' and not simply
'configure' to ensure that the configure script in the current
directory is run and not some other system-wide configure script.
The optional 'prefix' argument to configure gives the path to the
directory where the CFITSIO library and include files should be
installed via the later 'make install' command. For example,

 % ./configure --prefix=/usr1/local

will cause the later 'make install' command to copy the library
file(s) to /usr1/local/lib and the necessary header files to
/usr1/local/include (assuming of course that the process has
permission to write to these directories).

All the available configure options can be seen by entering the command

 % ./configure --help

The configure command customizes the Makefile for a particular
system, so after it has been run, type

 % make

at the prompt, and this will compile the source files and build
the library (static libcfitsio.a as well as the shared version
libcfitsio.so|.dylib).  Users may also wish to build the helper
utilities (fpack, funpack, fitscopy, imcopy, et al.) and test
program (testprog) using this command:

 % make utils

Finally, to copy the library and header file(s) to the chosen
install location, type this command:

 % make install


Alternatively, the library and utilities may be built on many
systems using the CMake program.  Specific instructions for using
CMake on Windows platforms can be found in the "README.win" file,
but for Unix systems (e.g., Linux or macOS) the procedure should
be similar to the following:

While in the CFITSIO source code directory:

 % mkdir cmbuild
 % cd cmbuild
 % cmake -G "Unix Makefiles" ..
 % cmake --build .
 % cmake --install . [--prefix /usr/local]

Where the final step uses an optional installation prefix.

Additional options for installing CFITSIO on macOS via third-party
package managers or the XCode GUI can be found in the README.MacOS
file.


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

The CFITSIO library may be tested by building and running the
testprog.c program that is included with the release (in the
"utilities" folder).  On Unix systems, type:

 % make testprog [or "make utils"]
 % ./testprog > testprog.lis
 % diff testprog.lis testprog.out
 % cmp testprog.fit testprog.std

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 mentioned above,
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 in the utilities folder 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.

Any problem reports or suggestions for improvements are welcome
and should be sent to the CFITSIO/CCFITS help desk at:

  [email protected]

-------------------------------------------------------------------------
William D. Pence
HEASARC, NASA/GSFC