$Id: INSTALL,v 1.5 2008/06/09 17:37:55 mdw Exp $

/********************************************************************
* Copyright (c) 1995 - 2004, EMBL, Peter Keller
* 
* CCIF: a library to access and output data conforming to the
* CIF (Crystallographic Information File) and mmCIF (Macromolecular
* CIF) specifications, and other related specifications.
* 
* This library is free software: you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* version 3, modified in accordance with the provisions of the 
* license to address the requirements of UK law.
*
* You should have received a copy of the modified GNU Lesser General 
* Public License along with this library.  If not, copies may be 
* downloaded from http://www.ccp4.ac.uk/ccp4license.php
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU Lesser General Public License for more details.
* 
********************************************************************/


            Installation instructions for the CCIF toolbox.
            ===============================================

Step I. You must have a POSIX interface to a regular expression package
(i.e. the routines regcomp, regexec, regerror and regfree). 

Some operating systems provide a native regex package as part of a
development option - one easy way to find out if you have it, is to try to
compile and link the following program:

#ifndef _POSIX_SOURCE   
#define _POSIX_SOURCE
#endif
#include <sys/types.h>
#include <regex.h>
main(){ regex_t preg;
        exit( regcomp(&preg, "a*", REG_EXTENDED) );
}

The location of the header file regex.h will usually be in /usr/include
under Unix. I have seen this file on at least one version of each of
AIX, OSF1, SunOS and HP-UX, although the version on SunOS 5.4 appears to
be broken (fixed under SunOS 5.5, though). Don't try to use the POSIX
regular expression package under VMS - this imposes all sorts of
difficulties when you come to actually run programs.

If you don't have a suitable library available on your system, I suggest
that you use GNU rx (available from the usual GNU archives, or as part of
your Linux distribution). There are still some niggling portability
problems with this package, though - if all else fails, use my patched
version of the rxdispencer package (currently available at
http://www.bath.ac.uk/~bsspak/ccif/rxd-pak.tar.gz). This version also
includes MAKE.COM files for VMS. Please note that this is a 'frozen'
product - I am not going to develop/support it. If you have problems with
GNU rx, you should notify rx's maintainer.

You may or may not want to install rx or rxdispencer on your system
area. Under Unix, you can control where the header files and library
archive goes, by specifying the apropriate options to rx's ./configure
script. If you want to keep it exclusive to your personal filestore under
Unix, don't do the 'make install' step.

Whatever your solution, it must be in place before building CCIF. See "Step
II" below, on how to specify the regular expression package to the build
process.

*ESV*ESV*ESV* On the ESV, also make sure that you have a file called
"strtod.c" in the same directory as the CCIF source, which contains code
for the strtod(3C) function. (I'm not going to go into explanations as to
why this is necessary.) I recommend the FreeBSD version, and I have put a
copy of it in the same place as the CCIF distribution.

Step II. (Unix) After unpacking the distribution file, run the configure
script to generate the makefile. The simplest case, is where you are using
gcc as the C compiler, your system's native Fortran compiler, and the
regular expression package files are at the system default location. In
this case, just type:

   ./configure

The script will run various checks on your system, and generate the
makefile. In other cases, you may need to set one or more of several
environment variables:

   (a) CC: the command to invoke your C compiler. It is only necessary to
set this where gcc is present on your system, but you don't want to use it.
If this is the case, set CC to 'cc' - on systems where 'cc' is not
appropriate, configure will automatically change the command and output a
message.

   (b) FC: the command to compile Fortran programs, which you are going to
use to call CCIF routines. Normally, you should be OK using your native
Fortran compiler, in which case you don't need to set FC. If you are going
to use another compiler (e.g. g77), set FC to that command. If are going to
specify compilation flags to the non-native Fortran compiler for your
CCIF-calling applications, also set FFLAGS as appropriate.

   (c) RX_H and RX_L: There are many different possibilities for the
various locations of the rx include files and library archive. Basically:
*IF* there is a system-provided regular expression package, *OR* there
isn't, but the GNU rx include files and librx.a are in directories which
are searched by default, don't set either of these variables. *IF* you need
to use rx, but in a non-default location, set RX_H and RX_L to the
directories which contain rxposix.h/rxgnucomp.h and librx.a respectively.

This should cover most cases. Setting RX_H will always override the native
regular expression package, and cause linking against librx.a - this is
recommended with SunOS 5.4 (see above). If the rx files are in the system
default locations, you can still override the choice of regex.h, by
defining RX_H to be '.' For the full works on this, look in "configure.in",
and follow the script logic.

You can define these environment variables like this:

   setenv CC cc    # csh/tcsh

or

   CC=cc           # sh/ksh/bash

With either shell, you can also use the 'env' command to pass them to
configure. For example, to use the native C compiler, but g77 as the
Fortran compiler, and where the rx files are in $HOME/include and
$HOME/lib, do:

   env CC=cc FC=g77 RX_H=$HOME/include RX_L=$HOME/lib ./configure

*ESV*ESV*ESV* The configure script cannot identify the system type correctly
on the ESV. Specify the host type after the configure command:

   env ....... ./configure mips-esv-bsd43


Step II (VMS) If you have the RX header files and LIBRX.OLB at the
system default locations, do nothing. If you need to specify the
location of the header files or LIBRX.OLB, define the logical names RX_H
and RX_L as the appropriate directories, e.g.

   define rx_h $disk1:[tools.include]
   define rx_l $disk1:[tools.lib]

Step III Type "make" (Unix) or "@MAKE" (VMS), and hope for the best. A
successful build will finish with a message about dumping the symbol table.
Under Unix, if you have a pre-ANSI C run-time library, you may get a
coredump during the build of 'star_scan.o'. If the build continues, this is
nothing to worry about. If you get a message about converting between
pointers and printable characters, please contact me for help.

After a successful build, you should have a file mmcifdic.lib, which
contains the dictionary in a binary format, and the toolbox library itself.
In most cases, this will be a shared library archive called libccif.so
(IRIX, SunOS, DEC OSF1), libccif.sl (HP-UX), or libccif.a (AIX). The static
archive library is called libccif.a (libccif-static.a under AIX). 

Under VMS, the object library file is called LIBCCIF.OLB; this file
contains pointers to the shared library executable LIBCCIFSHR.EXE. There is
also a static object library called LIBCCIF-STATIC.OLB.


                    Installing and using the toolbox
                    =================================

The shared library archive (or static archive on older systems) should be
simply moved to its destination directory. Under all Unix operating
systems, the link options used should be '-L<dir> -lccif', where <dir> is
the directory containing the archive. Under AIX, it is important that it is
not moved after any programs have been linked against it. For IRIX, SunOS
and DEC OSF1, the environment variable LD_LIBRARY_PATH should contain at
run-time a colon-separated list of directories to be searched for the
library (see the files shlib.csh and shlib.sh for how this can be set
up). Under HP-UX, the corresponding environment variable is called
SHLIB_PATH, but it is not necessary to set it, unless the shared library
has been moved after programs have been linked against it.

Under VMS, programs should be linked using "[<dir>]LIBCCIF/L", in the usual
way. At run time, the logical name LIBCCIFSHR should be defined as the full
pathname of LIBCCHFSHR.EXE. Alternatively, LIBCCIFSHR.EXE can be installed
as a known system executable, which may bring significant performance gains
(see the documentation on the VMS INSTALL utility for more details). Note
that this has not been tested, but LIBCCIFSHR.EXE contains no shareable,
writable sections.




                   Building the example programs.
                   ==============================

There are a few example programs which use CCIF. To build them under most
versions of Unix, you should only need to do

   make eg

Under VMS, do

   @MAKE EG

If your version of make is particularly dumb (like the one on the Convex), in
that it doesn't use the environment, you will need to do:

   make CCP4_LIB=$CCP4_LIB eg

In all cases, CCP4 has to be set up - if this is done with some local
command, such as "use ccp4", do this first.


                         Double precision
                         ================

The default build uses float's internally for real values. This can
lead to rounding errors on output. The configure script supports a
build which switches floats to doubles. Do:

   ./configure --enable-double

The Makefile will create the files libccif-dble.a and libccif-dble.so (or
whatever the OS-specific suffixes are). The REAL arguments to CCIF
functions will then match the Fortran DOUBLE PRECISION type. Most
modern Fortran compilers have a command-line option that compiles
REAL's as double-precision implicitly (e.g. f77 -r8 on DEC).

You should be able to use the same binary-transformed dictionary for
either library, as the only real number type that it holds (the mmCIF
default value for items of the 'float') is specified internally as a
double anyway.

The VMS build does not offer this directly. Edit MAKE.COM if you want
it.
