Installation Instructions
RasMol 2.7.2

Molecular Graphics Visualisation Tool
28 August 2000

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 have been made in August 2000 for RasMol version 2.7.2.

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

This is a very preliminary release of a version from the RasMol 2.7 series incorporating the "UCB" mods and other major changes. It is being released at this stage to solicit comments and suggestions, and is not intended for production use at this time.

IMPORTANT

This version is based directly on RasMol 2.7.1, 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.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

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

or on the web at:

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

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 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
Linux (Mandrake 7.1, i386):	RasMol.LINUX/Mandrake_7.1/i386/rasmol_8BIT.gz	rasmol.hlp.gz
	RasMol.LINUX/Mandrake_7.1/i386/rasmol_16BIT.gz	rasmol.hlp.gz
	RasMol.LINUX/Mandrake_7.1/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 (Mandrake 7.1, i386):	RasMol.LINUX/Mandrake_7.1/i386/rasmol_8BIT	rasmol.hlp
	RasMol.LINUX/Mandrake_7.1/i386/rasmol_16BIT	rasmol.hlp
	RasMol.LINUX/Mandrake_7.1/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

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" 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

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:

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"

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.