CCP4MAPWISH V1.0 - INSTALLATION INSTRUCTIONS
============================================

This file contains instructions on how to build the "ccp4mapwish" 
interpreter (a customised version of the Tcl/Tk interpreter "wish"). 
ccp4mapwish is required to run the MAPSLICER application, and is
relatively untested - so there is a good chance that the build will fail,
or that there will be problems with the interpreter once it is running.

Please e-mail any problems (and successes!) to pjx@ccp4.ac.uk ...
responses may be slow but I'm grateful for any/all feedback!

1. Files and Directories
------------------------

The ccp4mapwish-specific files required to build the program are in the
$CPROG/ccp4mapwish_ directory: 
  * C code is found in the c_src subdirectory
  * Fortran code is found in the fortran_src subdirectory

In addition the build requires:
  * A "tcl.h" header file for Tcl version 8.0 or better;
  * Tcl and Tk libraries for versions 8.0 or better;
  * CCP4 libraries;
  * Miscellaneous system libraries (detailed below in "Hints")

The supplied configure script will attempt to find all these things
automatically, so if you're lucky then you won't have to think about them
at all... :)

2. Building
-----------
Run the configure script: the syntax is
./configure <args> <system>
where <system> is one of irix, osf1 or linux

The optional arguments are:
--include-dir=<dir> : tells configure where to find tcl.h
--lib-dir=<dir>     : where to find tcl and tk libraries
--install-dir=<dir> : where to install the built ccp4mapwish executable
but you shouldn't need these.

If you aren't running on one of the three systems then you will
need to do some work... generate a Makefile and then edit the options
for the correct compiler flags. The options for FC, CC etc are the
same as the main suite so you can take them from e.g. $CPROG/Makefile

Please e-mail pjx@dl.ac.uk if you have problems (and/or successes)
with installing, as this information will be invaluable for improving
the code and the installation process in future.

Hints (1): Required libraries
-----------------------------
 To successfully build ccp4mapwish configure needs:

(1) tcl.h file for tcl version 8.0 or better
    configure searches for this and tests the major version.
    If you use an older version then you'll get errors about "Tcl_Obj"

(2) libtcl and libtk version 8.0 or better
    configure searches for these too.
    If you use older versions then you'll probably get errors about
    unresolved symbols starting with "Tcl_..." and/or "Tk_..."

(3) Fortran runtime libraries
    This is system specific - the known systems so far are:
    OSF1 : libUfor and libfor
    IRIX : libftn
    Linux/GNU: libg2c
    Check the fortran compiler man pages if you are using a different
system. Absence of these libraries will lead to unresolved symbols e.g. 
f_date

(4) X11 library
    Generally this should be libX11 and live in /usr/lib ... but this
might not be generally true e.g. for Linux it is in /usr/X11R6/lib
    At present configure doesn't do any searching for this; if it is
absent then you'll get unresolved symbols, probably starting with "X" or
"X11". 

(5) Maths library
    This is standard i.e. libm - if you don't have this then you're
probably in big trouble already anyway. 

(6) Miscellaneous libraries
    For OSF1 and IRIX the above are sufficient, if however you have
further unresolved symbols (e.g. Linux again...) then you'll have to try
and guess what's missing.

NB: it seems at least for some compilers that the order that libraries are
supplied in on the command line is also important. The ordering that seems
to work is: 
 -l(fortran_libs) -lm -l(miscellaneous) -lX11

Hints (2) - IRIX o32 vs n32
---------------------------
 There may be particular problems building under IRIX, since there are a
number of different possible conventions for compiling code (o)32, n32 and
64-bit. If the ccp4mapwish code is compiled under one convention, but the
main CCP4 libraries and/or the Tcl and Tk libraries are compiled under
another, then the build will fail.

If this is the case you will get an error message along the lines that one
of the files is e.g. o32 while another is n32. Ultimately the only
solution to this problem is to make sure that all the objects are of the
same type.
