                          Installation Instructions
                                RasMol 2.7.1

                                  [RasMol]
                    Molecular Graphics Visualisation Tool
                                22 June 1999

                     Based on RasMol 2.6 by Roger Sayle
    Biomolecular Structures Group, Glaxo Wellcome Research & Development
                        Stevenage, Hertfordshire, UK
           Version 2.6, August 1995, Version 2.6.4, December 1998
                      Copyright © Roger Sayle 1992-1999

                      and Based on Mods by Arne Mueller
                           Version 2.6x1, May 1998
                        Copyright © Arne Mueller 1998

              Version 2.7.0, 2.7.1 Mods by Herbert J. Bernstein
             Bernstein + Sons, P.O. Box 177, Bellport, NY, USA,
                        yaya@bernstein-plus-sons.com
                      2.7.0 March 1999, 2.7.1 June 1999
                 Copyright © Herbert J. Bernstein 1998-1999

The original RasMol manual was created by Roger Sayle. In July 1996, Dr.
Margaret Wong of the Chemistry Department, Swinburne University of
Technology, Australia, made extensive revisions to the RasMol 2.5 manual to
accurately reflect the operation of RasMol 2.6. Eric Martz of the University
of Massachusetts made further revisions. In May 1997, William McClure of
Carnegie Mellon University reorganized the HTML version of the manual into
multiple sections which could be downloaded quickly and added use of frames.
Portions of the 2.7.1 version of the RasMol manual were derived with
permission from William McClure's version using Roger Sayle's rasmol.doc for
version 2.6.4 as the primary source.

                   Documentation Last Updated 5 July 1999
           Edited by Herbert J. Bernstein and Frances C. Bernstein

  ------------------------------------------------------------------------

       THIS IS A PRELIMINARY RELEASE INVOLVING EXTENSIVE MODIFICATIONS
                        ***** USE WITH CAUTION ******

  ------------------------------------------------------------------------

                                  IMPORTANT

This version is based on RasMol version 2.6_CIF.2, on RasMol version 2.6x1
and on RasMol version 2.6.4. Please read the file NOTICE for important
notices which apply to this package. If you are not going to make changes to
RasMol, you are not only permitted to freely make copies and distribute
them, you are encouraged to do so, provided you do the following:

   * 1. Either include the complete documentation, especially the file
     NOTICE, with what you distribute or provide a clear indication where
     people can get a copy of the documentation; and
   * 2. Please give credit where credit is due citing the version and
     original authors properly; and
   * 3. Please do not give anyone the impression that the original authors
     are providing a warranty of any kind.

If you would like to use major pieces of RasMol in some other program, make
modifications to RasMol, or in some other way make what a lawyer would call
a "derived work", you are not only permitted to do so, you are encouraged to
do so. In addition to the things we discussed above, please do the
following:

   * 4. Please explain in your documentation how what you did differs from
     this version of RasMol; and
   * 5. Please make your modified source code available.

This version of RasMol is not in the public domain, but it is given freely
to the community in the hopes of advancing science. If you make changes,
please make them in a responsible manner, and please offer us the
opportunity to include those changes in future versions of RasMol.
  ------------------------------------------------------------------------

This file explains how to transfer, compile and install RasMol v2.7.1 on
your system. This version of the RasMol Molecular graphics package will run
on UNIX, VMS, Macintosh and Microsoft Windows.

  ------------------------------------------------------------------------

Obtaining RasMol v2.7.1

This version of RasMol may be obtained by anonymous FTP either by anonymous
FTP at:

ftp://ftp.bernstein-plus-sons.com/software/RasMol_2.7.1

or on the web at:

http://www.bernstein-plus-sons.com/software/RasMol_2.7.1

To transfer by anonymous ftp, type "ftp ftp.bernstein-plus-sons.com" on the
command line. Several seconds later you'll be prompted for a username. Use
the username "anonymous" and when asked for a password enter your e-mail
address. Once logged in, type the command "cd software/rasmol" to change the
directory to /software/rasmol and then type "binary" to avoid corrupting the
files during the transfer. For each file you wish to transfer, type "get
<filename>" and when you've finished type "quit". If these files are
subsequently transfered to other machines, please remember to transfer them
in BINARY mode. The file sizes should be identical before and after the
transfer.

NOTE: The Mac uses the "carriage return" character to signify the end of a
line, while UNIX machines use a "linefeed". If a file is transfered between
these two machines in "ASCII" mode all such characters are exchanged,
thereby corrupting the archive. Please ensure that you type the FTP command
"binary" before you transfer the file, indicating that the file should be
transfered without translation.

To build/rebuild RasMol 2.7.1 on any platform, you'll need to transfer the
following file:

 RasMol.tar.gzUNIX 'tar'ed 'gzip'ped archive containing the complete source
              code and documentation of the RasMol molecular graphics
              package.

To unpack the file on a UNIX machine type the command "gunzip RasMol.tar.gz"
and then the command "tar -xvf RasMol.tar" to extract the files in a
subdirectory under the current directory.

There are command-line and GUI-interface versions of tar and gzip for the
Macintosh and for Windows, so we have discontinued the former practice of
providing StuffIt or ZIP archives for those platforms. However, note that
MacIntosh-specific files are actually provided in gzipped MacBinary form
with a ".bin.gz" extension.

If you are in a hurry, the following pre-compiled binary files are
available: WARNING: ALL binaries and help files are gzipped!!!

 System      Binary                                      Help Files
 SGI (IRIX 5.3):
             RasMol.SGI/IRIX_5.3/rasmol_8BIT.gz          rasmol.hlp.gz
             RasMol.SGI/IRIX_5.3/rasmol_16BIT.gz         rasmol.hlp.gz
             RasMol.SGI/IRIX_5.3/rasmol_32BIT.gz         rasmol.hlp.gz

 SGI (IRIX 6.4):
             RasMol.SGI/IRIX_6.4/rasmol_8BIT.gz          rasmol.hlp.gz
             RasMol.SGI/IRIX_6.4/rasmol_16BIT.gz         rasmol.hlp.gz
             RasMol.SGI/IRIX_6.4/rasmol_32BIT.gz         rasmol.hlp.gz

 Alpha (OpenVMS 7.1)
             RasMol.DEC/OpenVMS_7.1/rasmol_8bit.exe.gz   rasmol.hlp.gz
             RasMol.DEC/OpenVMS_7.1/rasmol_16bit.exe.gz  rasmol.hlp.gz
             RasMol.DEC/OpenVMS_7.1/rasmol_32bit.exe.gz  rasmol.hlp.gz

 Alpha (Dunix 4.0D): 
             RasMol.DEC/Dunix_4.0D/rasmol_8bit.gz        rasmol.hlp.gz
             RasMol.DEC/Dunix_4.0D/rasmol_32bit.gz       rasmol.hlp.gz

 VAX (OpenVMS 6.2):
             RasMol.DEC/OpenVMS_6.2/rasmol_8bit.exe.gz   rasmol.hlp.gz
             RasMol.DEC/OpenVMS_6.2/rasmol_16bit.exe.gz  rasmol.hlp.gz
             RasMol.DEC/OpenVMS_6.2/rasmol_32bit.exe.gz  rasmol.hlp.gz

 Mac:        RasMac_FAT_8BIT.bin.gz                      rasmol.hlp.gz
             RasMac_PPC_8BIT.bin.gz
             RasMac_68K_8BIT.bin.gz
             RasMac_FAT_32BIT.bin.gz
             RasMac_PPC_32BIT.bin.gz
             RasMac_68K_32BIT.bin.gz


 Windows:    RasWin.exe.gz                               rasmol.hlp.gz,
                                                         raswin.hlp.gz

For those who have difficulty downloading "gzipped" files, uncompressed
files are available via the HTML web page only:
 System          Binary                                   Help Files
 SGI (IRIX 5.3): RasMol.SGI/IRIX_5.3/rasmol_8BIT          rasmol.hlp
                 RasMol.SGI/IRIX_5.3/rasmol_16BIT         rasmol.hlp
                 RasMol.SGI/IRIX_5.3/rasmol_32BIT         rasmol.hlp

 SGI (IRIX 6.4): RasMol.SGI/IRIX_6.4/rasmol_8BIT          rasmol.hlp
                 RasMol.SGI/IRIX_6.4/rasmol_16BIT         rasmol.hlp
                 RasMol.SGI/IRIX_6.4/rasmol_32BIT         rasmol.hlp

 Alpha (OpenVMS 7.1):
                 RasMol.DEC/OpenVMS_7.1/rasmol_8bit.exe   rasmol.hlp
                 RasMol.DEC/OpenVMS_7.1/rasmol_16bit.exe  rasmol.hlp
                 RasMol.DEC/OpenVMS_7.1/rasmol_32bit.exe  rasmol.hlp
 
 Alpha (Dunix 4.0D): 
                 RasMol.DEC/Dunix_4.0D/rasmol_8bit        rasmol.hlp
                 RasMol.DEC/Dunix_4.0D/rasmol_32bit       rasmol.hlp

 VAX (OpenVMS 6.2):
                 RasMol.DEC/OpenVMS_6.2/rasmol_8bit.exe   rasmol.hlp
                 RasMol.DEC/OpenVMS_6.2/rasmol_16bit.exe  rasmol.hlp
                 RasMol.DEC/OpenVMS_6.2/rasmol_32bit.exe  rasmol.hlp

 Mac:            RasMac_FAT_8BIT.bin                      rasmol.hlp
                 RasMac_PPC_8BIT.bin
                 RasMac_68K_8BIT.bin
                 RasMac_FAT_32BIT.bin
                 RasMac_PPC_32BIT.bin
                 RasMac_68K_32BIT.bin


 Windows:        RasWin.exe                               rasmol.hlp,
                                                          raswin.hlp

You will need both an appropriate binary and a copy of rasmol.hlp for each
system, and, under Windows, a copy of raswin.hlp for the WinHelp sub-system.

On an SGI, rename the appropriate binary as rasmol and copy it to
/usr/local/bin/rasmol (or to some appropriate location specified by the
environment variable PATH) and copy rasmol.hlp to
/usr/local/lib/rasmol/rasmol.hlp (or to the location indicated by the
environment variable RASMOLPATH)

  ------------------------------------------------------------------------

Installing RasMol v2.7.1

UNIX X11:

  1. In the src subdirectory: Type the command "xmkmf" to generate a
     "Makefile" for your particular system from the distributed Imakefile
     Alternatively (or if the first method fails), copy the file Makefile.in
     to Makefile, using the command "cp Makefile.in Makefile", then modify
     the contents of the Makefile to determine your local C compiler,
     compiler and linker options. The default set up is for an 8bit UNIX
     workstation with the X11 shared memory extension, compiled using the
     GNU C Compiler. Changing the line "CC=gcc" to "CC=cc" will use the
     machines native compiler but will require changing "CFLAGS" for your
     platform. A common problem is that SUN OpenWindows keeps its include
     files in the directory /usr/openwin/include/X11, hence the compiler
     directive -I/usr/openwin/include must be added to CFLAGS. A common
     problem on IBM RS6000s running AIX is that the MIT shared memory
     extensions to X windows are in the library -lXextSam, hence this must
     be added to the LIBS lines in either the Makefile or Imakefile.
  2. Modify the #defines in the file rasmol.h (see below) Note: IBMPC should
     not be defined.
  3. Compile the program using the UNIX make utility. (i.e. type "make")
  4. Place the 'rasmol' executable on the execution PATH, i.e.
     /usr/local/bin
  5. Install rasmol.hlp as /usr/local/lib/rasmol/rasmol.hlp (or at a
     loctaion indicated by the environment variable RASMOLPATH).
  6. If you have the UNIX utilities "uncompress" or "gunzip" ensure they are
     on the user's default PATH.
  7. Set the environment variable RASMOLPDBPATH to the directory containing
     the Broohaven PDB database, if one exits.
  8. Place any system wide initialisation parameters into the file
     "rasmolrc" in the directory pointed to by RASMOLPATH.
  9. It is possible to set-up RASMOLPATH and RASMOLPDBPATH each time the
     program is running by renaming rasmol to rasmol.exe, and using a script
     similar to the one in "rasmol.sh" of the standard distribution.
 10. If appropriate place "rasmol.1" or "rasmol.0" in the appropriate place
     for UNIX man pages, and optionally place "rasmol.html" somewhere in
     your WWW hierarchy (if available at your site).

MS Windows:

  1. Copy the executable RASWIN.EXE and the help files RASMOL.HLP and
     RASWIN.HLP to an appropriate directory. You may execute the program
     immediately by double-clicking the icon of RASWIN.EXE.
  2. Under Windows/95 and similar systems, create a shortcut icon to RasWin
     on the Desktop or in a folder. Select the RasWin icon then
     simultaneously press ALT-ENTER (or right click on the icon and select
     "Properties" from the menu). Select the "Shortcut" tab in the
     Properties dialog box.
  3. At the "Start In:" prompt, type in the path of the appropriate working
     directory.
  4. Under Windows 3.1 and similar systems Install the program in MS Windows
     using the New option of the Program Manager's File Menu. Set the
     Description of the Program to "RasWin v2.7.1" and the Current
     Directory, to the directory containing the files. Install the RasMol
     Help file using the New option of the Program, Manager's File Menu. Set
     the Description to "RasWin Manual", the command to "C:\WINDOWS\WINHELP
     RASWIN.HLP" and the working directory to the appropriate directory.

Macintosh and PowerMac:

  1. Place both "RasMac_FAT" (or "RasMac_PPC" or "RasMac_68k)" and
     "rasmol.hlp" in the same Macintosh folder

VAX/VMS:

  1. There is a VMS-ready copy of rasmol.h in the "src/vms" directory.
     Modify the #defines in the file rasmol.h (see below) Note: IBMPC,
     MITSHM and TERMIOS should not be defined.
  2. Copy all the files from the "src/vms" directory to the source
     directory.
  3. Copy the file "rasmol.hlp" from the "doc" directory to the source
     directory.
  4. If your VAX site has an MMS license type the command "MMS", otherwise
     use the DCL build script by typing "@build.com"
  5. The program may be run by typing "RUN RASMOL.EXE", the X Windows server
     is specified by a VMS command of the form:
     SET DISPLAY/CREATE/TRANSPORT=TCPIP/NODE=<hostname>
  6. The symbol RASMOL should be defined to be the path of RASMOL.EXE using
     :==
  7. The file doc/rasmol.vms contains a ascii VMS help file that can be
     compiled in to the VMS on-line help system.

  ------------------------------------------------------------------------

Recompiling RasMol v2.7.1

For both Windows and Mac, this version has been built with MetroWerks
CodeWarrior, and the necessary projects are included in the src/mswin and
src/mac directories. The following more general instructions adapted from
the RasMol v2.6 release are provided for your information, but have _not_
been tested against RasMol_2.7.1:

MS Windows v3.1:

  1. Use Makefile.pc instead of Makefile, by copying it to MAKEFILE.
  2. Modify the contents of the Makefile to determine your local C compiler,
     compiler and linker options.
  3. Modify the #defines in the file rasmol.h (see below) Note: EIGHTBIT and
     IBMPC should all be defined APPLEMAC, DIALBOX, MITSHM and TERMIOS
     should not be defined.
  4. Compile the program using the Microsoft Optimizing C Compiler Version
     7's (or Microsoft Visual C++'s) NMAKE program under MS-DOS.

MS Windows

  1. Using Microsoft Visual C++, create a new project adding all the "*.c"
     source files except "rasmol.c", "x11win.c", "rasmac.c" and
     "applemac.c". Add the Windows resource source file "raswin.rc". or
     alternatively use Makefile.nt by copying it to MAKEFILE.
  2. Follow the instructions from [2] onwards as for MS Windows v3.1.

Apple Macintosh and PowerMac

  1. Create a project in either the Symmantec C/C++, Think C or Metrowerks C
     compiler environments and add all the C source files ("*.c") to the
     project. On 68k development systems all C files should be placed in
     separate segments [however rasmac.c and applemac.c can share a segment
     and abstree.c and command.c can share a segment].
  2. Add the "rasmac.rsrc" resource file to the project.
  3. For the Symantec/Think C environment add the "ANSI" or "ANSI-small"
     library from "Standard Libraries" folder and the "MacTraps" library
     from the "Mac Libraries" folder. The choice of "ANSI" or "ANSI-small"
     is dependent upon the size of integer by the compiler. See dialog
     'Edit'->'Options'->'Think C..'->'Compiler Settings'. 2-byte integers
     require "ANSI-small" and 4-byte integers require "ANSI".
  4. A project files has been provided for Metrowerks 68K, PPC and FAT
     versions.
  5. If that project file is not satisfactory, for the Metrowerks 68K
     Compiler add the libraries "MacOS.lib" and "ANSI (2i) C.68K.Lib" to the
     project. [Note: If compiling for 4byte integer size and/or 68881 maths
     instructions select the approriate ANSI C Library].
  6. For some Metrowerks 68K compiler releases the "C/C++ Language Settings"
     "Enums Always Int" must be selected for proper execution.
  7. For the Metrowerks PPC Compiler add the libraries "MWCRuntime.Lib",
     "InterfaceLib", "MathLib" and "ANSI C.PPC.Lib". This should work fine
     for Metrowerks C++ v1.1. Apparently, Metrowerks C++ v1.2 also requires
     "console.stubs.c". [Thanks to Graham Palmer]
  8. In Metrowerk's "Edit" "Preferences" "Project" or Symmantec's "Project"
     "Set Project Type", set the project type to Application (Type 'APPL'),
     Creator 'RSML', and the SIZE flags to include "is32bitCompatible",
     "isHighLevelEventAware", "localAndRemoteHLEvents".
  9. Modify the #defines in the file "rasmol.h" (see below). Note: APPLEMAC
     should all be defined IBMPC, DIALBOX, MITSHM and TERMIOS should not be
     defined.
 10. Compile RasMol using the "Build Application..." Menu Item.
 11. To create a `fat' binary, use Apple's ResEdit to copy and paste the
     CODE, DATA and XREF resources from the Metrowerks 68K executable into
     the resource fork of the Metrowerks PPC executable.
 12. The Installed Application's name should be "RasMac v2.7.1"

  ------------------------------------------------------------------------

COMPILATION DIRECTIVES

The file rasmol.h contains a number of #define directives that control the
runtime behaviour of the program. The following directives may be defined or
undefined to suite the local site.

 THIRTYTWOBITThis determines whether RasMol will display and produce 8bit,
 SIXTEENBIT  16bit or 32(24) bit output. By default the symbol EIGHTBIT is
 EIGHTBIT    defined producing images with up to 256 colours. This symbol
             must be defined if IBMPC is defined.
 DIALBOX     This enables the use of a dials box, that is connected using
             the X Window System XInput extension. This option requires
             that the program be compiled with the Xi and Xext libraries.
             Note: libXi is called libXinput on some old machines, so
             requires the compiler option -lXinput!
 MITSHM      This option enables the use of the X Window System MIT shared
             memory extension. This enables images to be displayed faster
             when RasMol and the X11 server are running on the same host.
             This option requires the program be compiled with the Xext
             library. On IBM RS6000s runnning AIX, MITSHM also requires the
             XextSam library (which requires changing the Makefile or
             Imakefile). This is now enabled by default. This should be
             disabled on E&S ESV workstations as MITSHM support is not
             provided as standard.
 TERMIOS     This directive enables the command line processing on UNIXs
             that support the termios terminal handling routines. By
             leaving this symbol undefined, RasMol omits the interactive
             command line interface. Undefining is not recommended!
 SOCKETS     This directive enables the TCP/IP server functionality of
             RasMol to be enable. This enables other software to connect to
             a running RasMol. This should be undefined on machines not
             supporting BSD-style TCP/IP sockets (such as VMS).
 APPLEMAC    This determines whether the program is to run on an Apple
             Macintosh or PowerMac. By default, this option is disabled.
             The Macintosh code may be compiled to be either EIGHTTBIT or
             THIRTYTWOBIT and will generate images effectively.
 IBMPC       This determines whether the program is intended to run on an
             IBM PC or compatible. By default, this option is disabled.
 MSWIN       This determines whether the program is intended to run on an
             IBM PC or compatible under MS Windows. By default, this option
             is disabled.
 PROFILE     Defining PROFILE enables code to profile RasMol execution.

To summarise;

    A typical UNIX build:
         /* #define IBMPC        */
         /* #define MSWIN        */
         /* #define APPLEMAC     */
         #define X11WIN
         #define UNIX

         /* #define DIALBOX      */
         #define SOCKETS
         #define TERMIOS
         #define PROFILE
         #define MITSHM

    A typical Windows build:
        #define IBMPC
        #define MSWIN
        /* #define APPLEMAC      */
        /* #define X11WIN        */
        /* #define UNIX          */

        /* #define DIALBOX       */
        /* #define SOCKETS       */
        #define TERMIOS
        #define PROFILE
        #define MITSHM

    A typical Macintosh build:
        /* #define IBMPC         */
        /* #define MSWIN         */
        #define APPLEMAC
        /* #define X11WIN        */
        /* #define UNIX          */

        /* #define DIALBOX       */
        #define SOCKETS
        #define TERMIOS
        #define PROFILE
        #define MITSHM

    A typical VMS build:
       /* #define IBMPC          */
       /* #define MSWIN          */
       /* #define APPLEMAC       */
       /* #define X11WIN         */
       /* #define UNIX           */

       /* #define DIALBOX        */
       /* #define SOCKETS        */
       /* #define TERMIOS        */
       /* #define PROFILE        */
       /* #define MITSHM         */

Any comments, suggestions or questions about this modified version should be
directed to Herbert J. Bernstein at rasmol@bernstein-plus-sons.com.

  ------------------------------------------------------------------------
Updated 15 July 1999.
Herbert J. Bernstein
Bernstein + Sons, 5 Brewster Lane, Bellport, NY 11713-2803, USA
yaya@bernstein-plus-sons.com
+1-516-286-1339
