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), cfitsio.ps, or cfitsio.pdf 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 [--prefix=/target/installation/path]
 >  make          (or  'make shared')
 >  make install  (this step is optional)

at the operating system prompt.  The configure command customizes the
Makefile for the particular system, then the `make' command compiles the
source files and builds the library.  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 'make install' command to copy the CFITSIO libcfitsio file
to /usr1/local/lib and the necessary include files to /usr1/local/include
(assuming of course that the  process has permission to write to these
directories).

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_xxxx_borland.zip and cfitsiodll_xxxx_vcc.zip, where 'xxxx'
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.

When building on Mac OS-X, users should follow the Unix instructions,
above. Previous MacOS versions 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/ME/XP     Microsoft/Compaq Visual C++ v5.0, v6.0
   Windows 95/98/NT           Cygwin gcc
   OS/2                       gcc + EMX
   Mac OS 7.1 or greater      Metrowerks 10.+
   Mac OS-X 10.1 or greater   cc (gcc)

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
HEASARC, NASA/GSFC
email: William.D.Pence@nasa.gov

To build CFITSIO library on an Intel Mac as a Universal Binary

Unzip the library:
- tar xzf cfitsio3060.tar.gz (or whatever version this is)

- cd cfitsio/

- copy the cfitsio-xcodeproj.zip file here

- unzip cfitsio-xcodeproj.zip

- start Xcode and open cfitsio.xcodeproj

- expand the "Targets" menu under "Groups & Files"

- choose one of the following build options:

  * right-click on Build PPC -> Build "Build PPC"

  * right-click on Build i386 -> Build "Build i386"

  * right-click on Build x86_64 -> Build "Build x86_64"

  * right-click on Build Universal -> Build "Build Universal"
    (Builds all three of the above options, i.e. a Universal Binary
     usable on ppc, i386, and x86_64 architectures)

  (For some reason clicking on the menu "Build" icon doesn't seem to
   work correctly, but the right-click menus do).

-------------------------------------------------------

Another way to build the universal binary:

- unpack the cfitsio source code tar file
- cd cfitsio

Set the CFLAGS environment variable for building a Universal Binary:

  C-Shell variants:
  setenv CFLAGS "-arch ppc -arch i386 -arch x86_64 -g -O2"

  Bourne Shell variants:
  export CFLAGS="-arch ppc -arch i386 -arch x86_64 -g -O2"

Then proceed with the standard cfitsio build, i.e.:

- ./configure
- make
- make install


-------------------------------------------------------

Below, are the old (and now obsolete) instructions for building CFITSIO
on classic Mac OS-9 or earlier versions:

1. Un binhex and unstuff cfitsio_mac.sit.hqx
2. put CFitsioPPC.mcp in the cfitsio directory.
2. 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. It probably
won't work on 68k macs.  Also note that the fortran bindings aren't
included.  I haven't worked with the codewarrior f2c plugin so I don't know
how these would work.  If one is interested, please write and I can look
into this.

Instructions on building and using CFITSIO on Windows platforms
for C programmers using Microsoft Visual Studio or Borland C++.

These instructions for building the CFITSIO library under Windows use the
CMake build system that is available from http://www.cmake.org.

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

1.  Build the CFITSIO dll library

This step will create the cfitsio.dll, and cfitsio.lib files.  If you have
downloaded the CFITSIO DLL .zip file that already contains the pre-built
versions of these files, then SKIP THIS STEP.

  a. If CMAKE is not already installed on your machine, download it from
     http://www.cmake.org.  It is recommended that you choose the
     "Add CMake to the system PATH for current user" option during the
     installation setup process for convenience when running CMake later on.

  b. Unzip the CFITSIO .zip file (e.g. cfit3360.zip) that was obtained from
     the CFITSIO Web site (http://heasarc.gsfc.nasa.gov/fitsio/). This will
     create a new \cfitsio subdirectory that contains the source code and
     documentation files.  It should also contain a CMakeLists.txt file that
     will be used during the CMake build process.

  c. Open the Visual Studio Command Prompt window, likely using a
     desktop icon with this same name, (or the equivalent Borland command window)
     and CD (change directory) into the parent directory that is one level
     above the directory containing the CFITSIO source files that was created
     in the previous step.

  d. Create a new "cfitsio.build" subdirectory, and CD into it with the
     following commands:

     mkdir cfitsio.build
     cd cfitsio.build

     When using Visual Studio, all the files that are generated during the
     CMake process will be created in or under this subdirectory.

  e. Decide which CMake Generator you will want to use in the following step.
     This depends on which C/C++ compiler you are using and will likely have
     a name such as:

     "Visual Studio 10"
     "Visual Studio 10 Win64" (for 64-bit builds)
     "Visual Studio 11"
     "Visual Studio 11 Win64" (for 64-bit builds)
     "Visual Studio 12"
     "Visual Studio 12 Win64" (for 64-bit builds)
     "Borland Makefiles"
     "NMake Makefiles"

      You can see a list of all the available CMake Generators by executing
      the command

         cmake.exe /?

      Note that these names are case-sensitive and must be entered in the
      following step exactly as displayed.

  f.  Execute the following commands to build the CFITSIO library:

      cmake.exe -G "<cmake generator>" ..\cfitsio
      cmake.exe --build . --config Release

      Where the string <cmake generator> is the string that was selected
      in step e.  Note that the "..\cfitsio" argument in the first command
      gives the path to the directory that contains the CFITSIO source files
      and the CMakeLists.txt file.  The "." argument in the second command
      (following --build) tells CMake to build the files in the current
      directory (i.e., the cfitsio.build directory).

      If this process completes successfully, you should find the CFITSIO
      library files that were created in the "cfitsio.build\Release"
      subdirectory. To verify that CFITSIO is working correctly, execute the
      testprog.exe file (in that Release directory).  This should generate
      a long stream of diagnostic messages ending with the line "Status = 0:
      OK - no error".

   g. Other CMake options.

      CMake has many other build options that may be useful in some
      situations. Refer to the CMake documentation for more
      information.

      For example, one can build a 'debug' version of the CFITSIO library
      by executing the command "cmake.exe --build ." instead of the 2nd
      command listed above in section f.

      One can also make a thread safe version of CFITSIO using the
      pthread library with the following procedure:

      a. Download the precompiled files from the pthread-win32 project
      (http://sourceware.org/pthreads-win32/). Put the files for your
      specific  platform (.h, .lib, .dll) into a folder 'pthread',
      parallel to the  cfitsio source folder.

      b. For the compilation of cfitsio follow the cmake steps, but use
      this  change as a replacement for the commands in step f:

      cmake.exe -G "<cmake generator>" ..\cfitsio -DUSE_PTHREADS=1
       -DCMAKE_INCLUDE_PATH=..\pthread -DCMAKE_LIBRARY_PATH=..\pthread

      cmake.exe --build . --config Release

      You may need to adapt the paths for the source directory and
      the pthread library.

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

2.  Using CFITSIO when compiling and linking application programs

First, depending on your particular programming environment, it may be
necessary to copy the cfitsio.lib and cfitsio.dll files into another
directory where your compiler expects to find them.  Or equivalently, you
may need to specify the directory path to the location of the CFITSIO
library files when creating a project that uses them.  You may also need to
copy the fitsio.h and longnam.h include files from the \cfitsio source file
directory to a standard 'include' directory on your system.

When using the Visual Studio command line window, application programs can
be compiled and linked with CFITSIO using the following command:

		cl /MD your_program.c cfitsio.lib

The /MD command line switch must be specified to force the compiler/linker
to use the appropriate runtime library.   If this switch is omitted, then
the fits_report_error function in CFITSIO will likely crash.

When building programs in the Visual Studio graphical environment, one can
force the equivalent of the /MD switch by selecting 'Settings...' under the
'Project' menu, then click on the C/C++ tab and select the 'Code Generator'
category.  Then under 'User Run-time Library' select 'Multithreaded DLL'.

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

===============================================================================
===============================================================================
= NOTE:  This is the old version of the README.win32 file that was distributed
= with CFITSIO up until version 3.35 in 2013.  These instruction may still work
= with more recent versions of CFITSIO, however, users are strongly urged to
= use the CMake procedures that are now documented in the new README.win32 file.
===============================================================================
===============================================================================

     Instructions on using CFITSIO on Windows platforms for C programmers

These instructions use a simple DOS-style command window. It is also possible
to build and use CFITSIO within a GUI programming environment such as Visual
Studio, but this is not supported here.

===============================================================================
1.  Build the CFITSIO dll library

This step will create the cfitsio.def, cfitsio.dll, and cfitsio.lib files.
(If you downloaded the CFITSIO .zip file that contains the pre-built binary
.dll file, then SKIP THIS STEP).

  A. With Microsoft Visual C++:

      1. Open a DOS command window and execute the vcvars32.bat file that
         is distributed with older versions of Visual C++, or simply open
         the Visual C++ command window (e.g., when using Visual Studio 2010).

      2. Unpack the CFITSIO source files (cfitxxxx.zip) into a new empty directory

      3. In the DOS command window, cd to that directory and enter the
         following commands:

		nmake winDumpExts.mak
		nmake makefile.vcc
			(ignore the compiler warning messages)

  B: With  Borland C++:

     First, follow the instructions provided by Borland to set up
     the proper environment variables and configure files for the compiler.

     Unpack the cfitsio.zip source file distribution into a suitable directory.

     In a DOS command window, cd to that directory and then execute the
     makepc.bat batch file on the command line to build the CFITSIO library,
     and the testprog and cookbook sample programs.

===============================================================================
2.  Test the CFITSIO library with Visual C++

     Compile and link the testprog.c test program.  When using Visual Studio,
     the command is:

		cl /MD testprog.c cfitsio.lib


     This will create the testprog.exe executable program.  Running this
     program should print out a long series of diagnostic messages
     that should end with "Status = 0; OK - no error"

===============================================================================
3.  Compile and link an application program that calls CFITSIO routines
    with Visual C++

	Include the fitsio.h and longnam.h header files in the C source code.

	Link the program with the cfitsio.lib file:

		cl /MD your_program.c cfitsio.lib


	NOTE: The /MD command line switch must be specified on the cl
	command line to force the compiler/linker to use the
	appropriete runtime library.   If this switch is omitted, then
	the fits_report_error function in CFITSIO will likely crash.

	When building programs in the Visual Studio environment, one
	can force the equivalent of the /MD switch by selecting
	'Settings...' under the 'Project' menu, then click on the C/C++
	tab and select the 'Code Generator' category.  Then under 'User
	Run-time Library' select 'Multithreaded DLL'.