To use the FITSIO subroutines one must first build the CFITSIO library, which requires a C compiler. gcc is ideal, or most other ANSI-C compilers will also work. The CFITSIO code is contained in about 40 C source files (*.c) and header files (*.h). On VAX/VMS systems 2 assembly-code files (vmsieeed.mar and vmsieeer.mar) are also needed.
The Fortran interface subroutines to the C CFITSIO routines are located in the f77_wrap1.c, through f77_wrap4.c files. These are relatively simple 'wrappers' that translate the arguments in the Fortran subroutine into the appropriate format for the corresponding C routine. This translation is performed transparently to the user by a set of C macros located in the cfortran.h file. Unfortunately cfortran.h does not support every combination of C and Fortran compilers so the Fortran interface is not supported on all platforms. (see further notes below).
A standard combination of C and Fortran compilers will be assumed by default, but one may also specify a particular Fortran compiler by doing:
> setenv CFLAGS -DcompilerName=1(where 'compilerName' is the name of the compiler) before running the configure command. The currently recognized compiler names are:
g77Fortran IBMR2Fortran CLIPPERFortran pgiFortran NAGf90Fortran f2cFortran hpuxFortran apolloFortran sunFortran CRAYFortran mipsFortran DECFortran vmsFortran CONVEXFortran PowerStationFortran AbsoftUNIXFortran AbsoftProFortran SXFortranAlternatively, one may edit the CFLAGS line in the Makefile to add the '-DcompilerName' flag after running the './configure' command.
The CFITSIO library is built on Unix systems by typing:
> ./configure [--prefix=/target/installation/path] [--enable-sse2] [--enable-ssse3] > 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/localwill 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).
The optional -enable-sse2 and -enable-ssse3 flags will cause configure to attempt to build CFITSIO using faster byte-swapping algorithms. See the "Optimizing Programs" section of this manual for more information about these options.
By default, the Makefile will be configured to build the set of Fortran-callable wrapper routines whose calling sequences are described later in this document.
The 'make shared' option builds a shared or dynamic version of the CFITSIO library. When using the shared library the executable code is not copied into your program at link time and instead the program locates the necessary library code at run time, normally through LD_LIBRARY_PATH or some other method. The advantages of using a shared library are:
1. Less disk space if you build more than 1 program 2. Less memory if more than one copy of a program using the shared library is running at the same time since the system is smart enough to share copies of the shared library at run time. 3. Possibly easier maintenance since a new version of the shared library can be installed without relinking all the software that uses it (as long as the subroutine names and calling sequences remain unchanged). 4. No run-time penalty.The disadvantages are:
1. More hassle at runtime. You have to either build the programs specially or have LD_LIBRARY_PATH set right. 2. There may be a slight start up penalty, depending on where you are reading the shared library and the program from and if your CPU is either really slow or really heavily loaded.
On HP/UX systems, the environment variable CFLAGS should be set to -Ae before running configure to enable "extended ANSI" features.
It may not be possible to statically link programs that use CFITSIO on some platforms (namely, on Solaris 2.6) due to the network drivers (which provide FTP and HTTP access to FITS files). It is possible to make both a dynamic and a static version of the CFITSIO library, but network file access will not be possible using the static version.
On VAX/VMS and ALPHA/VMS systems the make_gfloat.com command file may be executed 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. Note that the getcwd function that is used in the group.c module may require that programs using CFITSIO be linked with the ALPHA$LIBRARY:VAXCRTL.OLB library. See the example link line in the next section of this document.
On Windows IBM-PC type platforms the situation is more complicated because of the wide variety of Fortran compilers that are available and because of the inherent complexities of calling the CFITSIO C routines from Fortran. Two different versions of the CFITSIO dll library are available, compiled with the Borland C++ compiler and the Microsoft Visual C++ compiler, respectively, in the files cfitsiodll_2xxx_borland.zip and cfitsiodll_3xxx_vcc.zip, where '3xxx' represents the current release number. Both these dll libraries contain a set of Fortran wrapper routines which may be compatible with some, but probably not all, available Fortran compilers. To test if they are compatible, compile the program testf77.f and try linking to these dll libraries. If these libraries do not work with a particular Fortran compiler, then there are 2 possible solutions. The first solution would be to modify the file cfortran.h for that particular combination of C and Fortran compilers, and then rebuild the CFITSIO dll library. This will require, however, a some expertise in mixed language programming. The other solution is to use the older v5.03 Fortran-77 implementation of FITSIO that is still available from the FITSIO web-site. This version is no longer supported, but it does provide the basic functions for reading and writing FITS files and should be compatible with most Fortran compilers.
CFITSIO has currently been tested on the following platforms:
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 MacOS 7.1 or greater Metrowerks 10.+CFITSIO will probably run on most other Unix platforms. Cray supercomputers are currently not supported.