Installation Instructions
RasMol 2.7.3

		Version		MAC PPC binaries		MSWIN binaries	RasWin Help File		LINUX binaries	RasMol Help File
		2.7.1		8     32		8	raw gz		8 16 32	raw gz
		2.7.1.1		8     32		8	raw gz		8 16 32	raw gz
		2.7.2		8     32		8	raw gz		8 16 32	raw gz
		2.7.2.1		8     32		8	raw gz		8 16 32	raw gz
		2.7.2.1.1		8     32		8	raw gz		8 16 32	raw gz
		2.7.3		8     32		8	raw gz		8 16 32	raw gz
	See Source Code and Binaries for more.

Molecular Graphics Visualisation Tool
6 February 2005

with RasMol 2.7.3 incorporating changes by Clarice Chigbo, Ricky Chachra, and Mamoru Yamanishi

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.

Translations

Thanks to the efforts of José Miguel Fernández Fernández (Departamento de Bioquímica y Biología Molecular. Universidad de Granada. España (jmfernan@ugr.es)) a translation of the Manual for Rasmol version 2.7.1 into Spanish is now available. La traducción española del manual de la versión de la Dra. Wong revisada por Eric Martz fue realizada por Isabel Serván Martínez y José Miguel Fernández Fernández. La actual traducción del Manual de RasMol 2.7.1 ha sido realizada usando como base la anterior de RasMol 2.6 por  José Miguel Fernández Fernández.

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.

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

IMPORTANT

This version is based in directly on RasMol version 2.7.2.1.1, on RasMol version 2.7.2, on RasMol version 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 and for license terms (GPL or RASLIC).

Obtaining RasMol v2.7.3

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.3

or on the web at:

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

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.3 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!!! Uncompressed binaries are also available in the second section of each page.

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.3

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.3

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.3:

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. Note that later versions of CodeWarrior no longer support 68K builds. You will need an old CodeWarrior 5.3 kit for such builds.
5. Project files have been provided for Metrowerks 68K, PPC and FAT versions.
6. 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].
7. For some Metrowerks 68K compiler releases the "C/C++ Language Settings" "Enums Always Int" must be selected for proper execution.
8. 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]
9. 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".
10. 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.
11. Compile RasMol using the "Build Application..." Menu Item.
12. 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.
13. 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.