This document outlines practical issues arising from differences between the CCP4 libraries in CCP4 5.0 and older versions of the suite. It also outlines how to deal with these.
In CCP4 5.0, the old monolithic library libccp4 is now split into three components:
This means that compilation lines of the form
f77 -o foo foo.f -L$CCP4_LIB -lccp4
will no longer work, as there is no libccp4.
(Nb CCP4_LIB is the environment variable set in ccp4.setup to point to
the location where the CCP4 libraries are installed.)
libccp4c contains the functions needed for handling MTZ and CCP4 map files, symmetry handling, and many other low-level functions (see library docs for info). C programs can now access these functions directly by linking against libccp4c only, e.g.:
cc -o foo foo.c -L$CCP4_LIB -lccp4c
libccp4f provides Fortran APIs to the core functions (plus some dedicated Fortran code). Fortran programs using MTZ and/or CCP4 map files, or utilising the CCP4 environment, file opening, error reporting etc, must link against both libccp4f and libccp4c, e.g.:
f77 -o foo foo.f -L$CCP4_LIB -lccp4f -lccp4c
libmmdb provides functionality for handling coordinate data, including reading and writing PDB and mmCIF files. Fortran programs which also use the PDB handling functions provided in the old libccp4 must also link against libmmdb. It is likely that the C++ and maths libraries provided by the system will also have to be linked in explicitly when using the Fortran compiler, e.g.:
f77 -o foo foo.f -L$CCP4_LIB -lccp4f -lccp4c -lmmdb -lC -lm
If you experience problems with undefined symbols then it is recommended that you look at the options used when compiling one of the CCP4 programs, either by looking at the Makefile generated in the $CPROG, or else by performing make <program> and looking at the compile line echoed to the screen.
The file $CLIBS/library.h which was present in pre-5.0 versions of CCP4 has been removed in V5.0. library.h contained macro definitions for various platforms along with prototypes for various low-level library functions(most of which are no longer relevant in v5.0).
You will need to replace references to library.h with ccp4_sysdep.h. If you use the C library function ccp4_fatal then you will also need to include ccp4_errno.h. Both header files are in the $CLIBS directory, and are also copied to the $CINCL directory upon installation of the CCP4 libraries.
As far as possible the CCP4 5.0 libraries provide a Fortran API which duplicates that in earlier releases of the suite. Therefore it should not be necessary to change any application source code in order to link against the 5.0 libraries.
In practice this may not always be the case, so please report problems to CCP4 via ccp4@ccp4.ac.uk as it is possible that you have found a bug.
MTZ files associate metadata with each column, in addition to the actual data. In the past this metadata has consisted of dataset and project names, which were originally used in data harvesting.
In CCP4 5.0 MTZ files associate each column of data with a dataset which is identified by a crystal name/dataset name pair. A single file can contain multiple datasets, each with a unique crystal-dataset name pair. Each dataset also has associated data (project name, wavelength and cell parameters). In addition to the crystal-dataset pairs defined by the application program, the CCP4 5.0 libraries always create a HKL_base dataset, to associate with the indices H, K and L.
For the background on crystals and datasets see the DATA MODEL section in the MTZ format document.
Programs which did not previously make use of crystals and datasets should not require changes to use the new libraries. However there are a number of functions in the Fortran API which can be used to read and manipulate this information. These can be found in the FORTRAN API section of the MTZlib documentation, under the heading Subroutines for handling Dataset Information. Also, template Fortran programs which handle MTZ files can be found in the Developers Area of the CCP4 website.
Pre-CCP4 5.0 new columns added to MTZ files would appear to be "appended", that is they would appear at the end of the list of columns in the file.
In CCP4 5.0 the MTZ data is stored in memory grouped by parent crystal and dataset, so new columns appear to be appended to the dataset they are assigned to.
This means that the ordering of columns within the files can no longer be assumed, and this has implications for some older programs which make assumptions about certain columns being in a certain position within the file. It also has implications for any system which makes these assumptions when viewing e.g. the output of the MTZDUMP program.
Programs using the MTZ libraries and files for CCP4 5.0 need to be updated to check the position of the columns of interest.
Pre CCP4 5.0 the libraries read symmetry information from the symop.lib file. This is an ASCII text file which stores information on each spacegroup, including spacegroup number, different names, list of symmetry operators etc.
In CCP4 5.0 the libraries use a new file syminfo.lib. This contains the information also found in symop.lib plus additional information (e.g. Hall symbols) and is in a different format to symop.lib. However symop.lib is still distributed as part of the suite.
Both files can be found in the $CLIBD directory. For programs that use the CCP4 preprocessor subroutine CCPFYP, the environment variables SYMINFO and SYMOP are set by default to $CLIBD/syminfo.lib and $CLIBD/symop.lib respectively. These settings can be over-riden by setting the variables in the shell, or by specifying values on the command line.
Spacegroup names returned from the CCP4 5.0 libraries may be in a different format to those returned by pre 5.0 libraries, and may contain spaces (which can confuse some applications).
If an application parses or otherwise uses spacegroup names returned from the CCP4 libraries then please check whether this will cause a problem.
Files produced from older versions of the CCP4 libraries should be compatible with the 5.0 libraries, and files produced with the 5.0 libraries should be compatible with programs using older versions of the libraries (although some information may not be recognised).
Some problems have been reported when using third-party programs which use their own functions and/or subroutines to read and write CCP4 formatted files. In these cases the recommendation is that the programs should be modified to use the CCP4 libraries to handle these files.
If you discover any issues associated with using the CCP4 5.0 libraries which are not covered here then please contact CCP4 at ccp4@ccp4.ac.uk.
Peter Briggs 5th March 2004