
   [IUCr Home Page] [CIF Home Page] [RasMol] 
     _________________________________________________________________
   
    | Copying and Distribution | Contents | Installation Instructions |
    | Changes | Things To Do | Introduction | Source Code and Binaries |
                     | RasMol Manual | Release README |
                                      
                         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.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.
   
   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:
   
   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.
   
   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.
   
    | Copying and Distribution | Contents | Installation Instructions |
    | Changes | Things To Do | Introduction | Source Code and Binaries |
                     | RasMol Manual | Release README |
     _________________________________________________________________
   
   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
