                         Installation Instructions
                              RasMol 2.7.2.1.1

                   Molecular Graphics Visualisation Tool
                              26 January 2004

                     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 (C) Roger Sayle 1992-1999

                            and Based on Mods by

   Author Version, Date Copyright
   Arne Mueller RasMol 2.6x1 May 1998 (C) Arne Mueller 1998
   Gary Grossman and
   Marco Molinaro RasMol 2.5-ucb November 1995
   RasMol 2.6-ucb November 1996 (C) UC  Regents/ModularCHEM
   Consortium 1995, 1996
   Philippe Valadon RasTop 1.3 August 2000 (C) Philippe Valadon 2000
   Herbert J. Bernstein RasMol 2.7.0 March 1999
   RasMol 2.7.1 June 1999
   RasMol 2.7.1.1 January 2001
   RasMol 2.7.2 August 2000
   RasMol 2.7.2.1 April 2001
   RasMol 2.7.2.1.1 January 2004
   Copyright (C) Herbert J. Bernstein 1998-2004

                     and Incorporating Translations by

   Author Item Language
   Isabel Servan Martinez,
   Jose Miguel Fernandez Fernandez 2.6 Manual Spanish
   Jose Miguel Fernandez Fernandez 2.7.1 Manual Spanish
   Fernando Gabriel Ranea 2.7.1 menus and messages Spanish
   Jean-Pierre Demailly 2.7.1 menus and messages French
   Giuseppe Martini, Giovanni Paolella,
   A. Davassi, M. Masullo, C. Liotto 2.7.1 menus and messages
   2.7.1 help file Italian

                              This Release by
    Herbert J. Bernstein, Bernstein + Sons, P.O. Box 177, Bellport, NY,
                                    USA
                        yaya@bernstein-plus-sons.com
                 Copyright (C) Herbert J. Bernstein 1998-2001

   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. Changes were made in August 2000 for RasMol
   version 2.7.2, January 2001 for RasMol version 2.7.1.1 and April 2001
   for RasMol version 2.7.2.1.

                  Documentation Last Updated 21 April 2000
          Edited by Herbert J. Bernstein and Frances C. Bernstein

                                Translations

   Thanks to the efforts of Jose Miguel Fernandez Fernandez (Departamento
   de Bioquemica y Biologia Molecular. Universidad de Granada. Espana
   (jmfernan@ugr.es)) a translation of the Manual for Rasmol version
   2.7.1 into Spanish is now available. La traduccion espanola del
   manual de la version de la Dra. Wong revisada por Eric Martz fue
   realizada por Isabel Servan Martinez y Jose Miguel Fernandez
   Fernandez. La actual traduccion del Manual de RasMol 2.7.1 ha sido
   realizada usando como base la anterior de RasMol 2.6 por  Jose Miguel
   Fernandez Fernandez.

   Thanks to translations by Fernando Gabriel Ranea in late 2000 and
   early 2001, RasMol is now capable of rendering most menu items and
   messages in Spanish. Jean-Pierre Demailly provided French translations
   of menus and messages in January 2001. Giuseppe Martini and Giovanni
   Paolella with contributions by A. Davassi, M. Masullo and C. Liotto
   provided Italian translation of menus and messages in March 2001.
     _________________________________________________________________

                             Production Release

   RasMol 2.7.2.1.1 is the production release of version 2.7.2 of the
   RasMol 2.7 series. Aside from code cleanups to avoid compiler warning
   messages, and one bug fix (to allow reading of the RCSB PDB mmCIF
   extensions data sets), this release is the same as the April 2001
   2.7.1.1 release.
     _________________________________________________________________

                    IMPORTANT - Copying and Distribution

   This version is based directly on RasMol version 2.7.2, on RasMol
   2.7.1.1, on RasTop 1.3, on RasMol version 2.6_CIF.2, on RasMol version
   2.6x1, on RasMol version 2.6.4, and RasMol 2.5-ucb and 2.6-ucb. 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.2.1.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.2.1.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.2.1.1

   or on the web at:

   http://www.bernstein-plus-sons.com/software/RasMol_2.7.2.1.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.2.1.1 on any platform, you'll need to
   transfer the following file:

   RasMol.tar.gz UNIX '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.

   Important Note for Mac OS X: If you simply unpack the tar under Mac OS
   X, but use an application to compile, such a CW 5.3, to compile under
   Mac Classic, you will need to set the creator and type using SetFile
   in the Apple Developer Tools. You will also need to make similar
   settings for the sample data files in the data directory. The scripts
   src/CW_fixup.csh and data/RSML_fixup.csh are provided to assist in
   this fixup after you have installed the Apple Developer Tools.

   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
   Linux (RedHat 7, i386): RasMol.LINUX/RedHat_7/i386/rasmol_8BIT.gz
      rasmol.hlp.gz
        RasMol.LINUX/RedHat_7/i386/rasmol_16BIT.gz rasmol.hlp.gz
     RasMol.LINUX/RedHat_7/i386/rasmol_32BIT.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:

      System Binary Help Files
   Linux (RedHat 7, i386): RasMol.LINUX/RedHat_7/i386/rasmol_8BIT
      rasmol.hlp
        RasMol.LINUX/RedHat_7/i386/rasmol_16BIT rasmol.hlp
        RasMol.LINUX/RedHat_7/i386/rasmol_32BIT 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.2.1.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.2.1.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.2.1.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.2.1.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.2.1.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.

   THIRTYTWOBIT
   SIXTEENBIT
   EIGHTBIT This determines whether RasMol will display and produce 8bit,
   16bit or 32(24) bit output. By default the symbol EIGHTBIT is 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 16 February 2004.
   Herbert J. Bernstein
   Bernstein + Sons, 5 Brewster Lane, Bellport, NY 11713-2803, USA
   yaya@bernstein-plus-sons.com
