2.1 Building the Library

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
 SXFortran

Alternatively, 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/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).

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 it may be necessary to modify the file "cfortran.h" to support that particular combination of C and Fortran compilers, and then rebuild the CFITSIO dll library. This will require, however, some expertise in mixed language programming.

CFITSIO should be compatible with most current ANCI C and C++ compilers: Cray supercomputers are currently not supported.