This document is intended as a simple guide aimed at users of CCP4 who have little or no experience of programming, and who are unsure of how to implement the program fixes which are advertised through the CCP4 Problems Page.
Fixes come in two forms: as a source code patch, or as a complete new source code file in the CCP4 Prerelease area.
A patch is a minor change to a program source code (files ending in .f, .c, .h, .cpp and others) which is intended to fix a specific problem. CCP4 patches are generated using the Unix diff command, which compares two files and produces the information required to change the first into the second. The form of the output varies depending on the options used with diff, as shown below.
A typical example of the output from a basic diff is:
diff subag_old.f subag_new.f
88c88
< BAVER_CURRENT = BAVER_CURRENT+U_ANISO(IA,1)
---
> BAVER_CURRENT = BAVER_CURRENT+U_ANISO(IA,1)*PISQ8
93,94c93,94
< CALL U2ISOBEQUAV(UANISO_INIT,UISO_EQUAV)
< BAVER_CURRENT = BAVER_CURRENT + UISO_EQUAV
---
> CALL U2ISOBEQUAV(UANISO0,UISO_EQUAV)
> BAVER_CURRENT = BAVER_CURRENT + UISO_EQUAV*PISQ8
You can read this as follows. Lines such as 88c88 or 93,94c93,94 precede chunks
of differences - the numbers refer to the line numbers in the first and second
files and the "c" indicates that these lines were changed. (They could also
have been added, if the line contains an a instead of a c,
or deleted if it contains a d.)
You know which file each line in a chunk of differences comes from by looking at the < and > symbols at the start (lines from the first file are marked by < and those from the second by >)
A typical example of the output from a context diff is:
diff -c linalgebra.f linalgebra_new.f
*** linalgebra.f Thu Jul 22 14:53:02 1999
--- linalgebra_new.f Thu Jul 22 14:31:52 1999
***************
*** 247,253 ****
DO J=1,N
DO I=1,N
DO K=1,N
! AMAT_OUT(I,K) = AMAT_OUT(I,K) + AMAT1(K,I)*AMAT2(K,J)
ENDDO
ENDDO
ENDDO
--- 247,253 ----
DO J=1,N
DO I=1,N
DO K=1,N
! AMAT_OUT(I,K) = AMAT_OUT(I,K) + AMAT1(J,I)*AMAT2(J,K)
ENDDO
ENDDO
ENDDO
***************
*** 285,291 ****
DO J=1,N
DO K=1,N
DO I=1,N
! AMAT_OUT(I,K) = AMAT_OUT(I,K) + AMAT1(K,I)*AMAT2(J,K)
ENDDO
ENDDO
ENDDO
--- 285,291 ----
DO J=1,N
DO K=1,N
DO I=1,N
! AMAT_OUT(I,K) = AMAT_OUT(I,K) + AMAT1(J,I)*AMAT2(K,J)
ENDDO
ENDDO
ENDDO
This looks quite different to the basic diff, but is still split into chunks of altered code (separated by asterisks). Within each chunk, the first block consists of lines from the old file and the second of lines from the new file (preceded in each case by the line numbers). The affected lines in each block are marked with a "!" at the start.
Although context diffs are more verbose, the additional information that they contain should help to clarify the changes in the event e.g. that line numbers don't match up.
There are two steps: apply the patch to the program source code, then compile the fixed code to generate the fixed executable.
There are various ways to make the changes to the program source code:
| System | Recommended patch syntax |
|---|---|
| Alpha | patch -i patch_file orig_file |
| Linux | patch orig_file patch_file |
| SGI | patch orig_file patch_file |
| Sun | patch -i patch_file orig_file |
If patch fails ...
This may be because we have given a patch for the fix from developmental code,
rather than from that in the last CCP4 distribution. In this case line numbers
may not match up and this can confuse patch (though for simple cases
at least it seems to be able to cope).
If you do get a failure (patch should let you know when something has gone wrong) then you may have to resort to making the change by hand. If you have severe problems let us know!
Once you have applied the patch you will need to recompile. If the patch was for a program then you should simply be able to type make prog_name in the directory holding the fixed code. If the compilation is okay then you should move the resulting file to the $CBIN directory using make install prog_name.
If the change was to a library then this is more complicated: in the library source directory $CLIBS type make to rebuild the libraries, and then install them in the appropriate place using the make install command. If you have shared libraries then this is all you need to do; otherwise you also need to recompile and reinstall the affected programs (those that call the fixed subroutines), as described above.
As described in section 1.1, patches are generated using the diff command, and depending on the options used will give slightly different output. For example, diff -c ("context diff") will output unchanged lines surrounding the changes - this is the one we recommend, as it makes it easier to find the changes even if line numbers don't match up for whatever reason.
See man diff for a complete description of the options and output.
The ordering of the two files which are differenced is important. You should always use:
diff [options] old_file new_file > patch_file
If you get it wrong then the patch file will be reversed. Take care not to send out reversed patches, since it makes people wonder whether they've already applied the patch.
Patches may also be supplied for other files, notably files used in the CCP4 interface ccp4i (files ending in .tcl, .def, .script and .com). These patches should be applied as above. There is no compilation step in this case. For ccp4i, you need to re-start the interface to make sure the patched files are used, but that is all.
CCP4 patches tend to be relatively short; if the changes are substantial then a complete version of the fixed program will be placed on the CCP4 "prerelease ftp area" at ftp://ftp.ccp4.ac.uk/ccp4/prerelease.
In this case, you should fetch the new file and overwrite the old version with it (make sure you make a back-up copy first!), then recompile as described above in section 1.3.
In general, we don't expect that Windows users will have a compiler (although you can buy a compiler for Windows, and CCP4 will compile under Windows). Therefore, the above section on applying source code patches is not relevant, since you won't be able to compile the patched source code file. In some cases, we will provide a prerelease executable (see above) for you - otherwise you will have to wait for the next CCP4 release.
However, there are other fixes that do not require re-compilation, for example updated .tcl files for the ccp4i GUI. You are unlikely to have the patch program, so we will provide a complete fixed file in these cases. If you get such a file, you need to copy it over the equivalent file in your CCP4 distribution (we'd always advise backing-up the original!). You will probably need to restart ccp4i.