home *** CD-ROM | disk | FTP | other *** search
/ Organic Chemistry (8th Edition) / Image.iso / pc / edugen / rasmol / INSTALL < prev    next >
Text File  |  1996-09-25  |  16KB  |  331 lines
  1.  
  2.                             RasMol 2.6
  3.               Molecular Graphics Visualisation tool.
  4.  
  5.                            Roger Sayle 
  6.                   Biomolecular Structures Group
  7.               Glaxo Wellcome Research & Development
  8.                   Stevenage, Hertfordshire, UK.
  9.                           September 1995
  10.  
  11.  
  12.     This file explains how to transfer, compile and install RasMol v2.6 on
  13. your system. This version of the RasMol Molecular graphics package will 
  14. run on UNIX, VMS, Macintosh and Microsoft Windows (OS/2 and Windows NT). 
  15.  
  16. [1] Obtaining RasMol v2.6
  17. =========================
  18.  
  19. The current version of RasMol may be obtained by anonymous FTP from 
  20. either ftp.dcs.ed.ac.uk in the directory /pub/rasmol or from 
  21. src.doc.ic.ac.uk in the directory /packages/rasmol. These sites are
  22. also mirrored at several other locations around the world. RasMol may
  23. also be obtained by electronic mail by sending the message "help software"
  24. to "netserv@embl-heidelberg.de". Follow the instructions provided by
  25. EMBL for unpacking the software from the e-mail messages.
  26.  
  27. To transfer by anonymous ftp, type "ftp ftp.dcs.ed.ac.uk" on the command
  28. line. Several seconds later you'll be prompted for a username. Use the
  29. username "anonymous" and when asked for a password enter your e-mail
  30. address. Once logged in, type the command "cd pub/rasmol" to change
  31. the directory to /pub/rasmol and then type "binary" to avoid corrupting
  32. the files during the transfer. For each file you wish to transfer, type
  33. "get <filename>" and when you've finished type "quit". If these files 
  34. are subsequently transfered to other machines, please remember to
  35. transfer them in BINARY mode. The file sizes should be identical before
  36. and after the transfer.
  37.  
  38. The problem with rasmac.sit.hqx being reported as a corrupt StuffIt/BinHex 
  39. archive is caused by FTP the end-of-line characters between UNIX and 
  40. Macintosh platforms. The Mac uses the "carriage return" character to
  41. signify the end of a line, while UNIX machines use a "linefeed". If a
  42. file is transfered between these two machines in "ASCII" mode all such
  43. characters are exchanged, thereby corrupting the archive. Please ensure
  44. that you type the FTP command "binary" before you transfer the file, 
  45. indicating that the file should be transfered without translation.
  46. Apparently using StuffIt or StuffIt Lite will not work directly. First use
  47. BinHex to unhex the file rasmac.sit and then use StuffIt to extract and
  48. uncompress the source files and executable. When using BinHex please 
  49. make sure the "TEXT filter" option on the File Menu is disabled.
  50. Alternatively, if you are transfering via a local UNIX machine, use the
  51. command, `tr "\015" "\012" < rasmac.sit.hqx > temp.sit.hqx' to translate
  52. all the carriage returns to linefeeds thus avoiding the problem.
  53.  
  54. Depending upon the type of machine, you'll need to transfer one or more 
  55. of the following files:
  56.  
  57.     RasMol2.tar.Z    UNIX 'tar'ed 'compress'ed archive containing the
  58.                         complete source code and documentation of the
  59.                         RasMol molecular graphics package.
  60.  
  61.     RasMol2.tar.gz  UNIX 'tar'ed 'gzip'ed archive containing the 
  62.                         complete source code and documentation of the
  63.                         RasMol molecular graphics package.
  64.  
  65.         rasmac.sit.hqx  Apple Macintosh 'BinHex' and 'StuffIt' archive
  66.                         of the RasMol source code including a 'fat'
  67.                         binary for both Macintosh and PowerMac.
  68.  
  69.         raswin.zip      MS-DOS PkZip archive of the MS Windows version
  70.                         of the RasMol source code including a binary
  71.                         for MS Windows v3.1.
  72.  
  73.         rasmenu.zip     MS-DOS PkZip archive of the Visual Basic Graphical
  74.                         User Interface to RasMol including executable.
  75.  
  76.  
  77. To unpack the file RasMol2.tar.Z on a UNIX machine type the command
  78. "uncompress RasMol2.tar.Z" and then the command "tar -xvf RasMol2.tar"
  79. to extract the files in a subdirectory under the current directory.
  80. Once the files have been sucessfully extract, you can delete the
  81. file RasMol2.tar with the command "rm RasMol2.tar".
  82.  
  83. To unpack the file RasMol2.tar.gz on a UNIX machine, type "gunzip
  84. RasMol2.tar.gz" to use GNU gunzip to uncompress the files. Then
  85. follow the instructions above.
  86.  
  87. To unpack the file rasmac.sit.hqx, start up the application "StuffIt 
  88. Expander" and select the option "Exapnd" from the "File" menu. This
  89. should create the folder "RasMol2". You can then delete the files
  90. "rasmac.sit.hqx" and "rasmac.sit" by dragging their file icon and
  91. dropping them on the "trash can".
  92.  
  93. To unpack the files raswin.zip and rasmenu.zip, type the command
  94. "pkunzip -d raswin.zip" and "pkunzip -d rasmenu.zip". You must have
  95. version 2.04 or later of PKUNZIP.EXE
  96.  
  97.  
  98. [2] Installing RasMol v2.6
  99. ==========================
  100.  
  101. UNIX X11:
  102. ---------
  103. [1] Type the command "xmkmf" to generate a "Makefile" for your particular 
  104.     system from the distributed Imakefile 
  105.  
  106.     Alternatively (or if the first method fails), copy the file Makefile.in
  107.     to Makefile, using the command "cp Makefile.in Makefile", then modify 
  108.     the contents of the Makefile to determine your local C compiler,
  109.     compiler and linker options. The default set up is for an 8bit UNIX
  110.     workstation with the X11 shared memory extension, compiled using the
  111.     GNU C Compiler. Changing the line "CC=gcc" to "CC=cc" will use the
  112.     machines native compiler but will require changing "CFLAGS" for your
  113.     platform.
  114.  
  115.     RasMol may be built for E&S workstations using the command "make esv".
  116.  
  117.     A common problem is that SUN OpenWindows keeps its include files in the
  118.     directory /usr/openwin/include/X11, hence the compiler directive 
  119.     -I/usr/openwin/include must be added to CFLAGS.
  120.  
  121.     A common problem on IBM RS6000s running AIX is that the MIT shared
  122.     memory extensions to X windows are in the library -lXextSam, hence
  123.     this must be added to the LIBS lines in either the Makefile or Imakefile.
  124.  
  125. [2] Modify the #defines in the file rasmol.h (see below)
  126.         Note: IBMPC should not be defined.
  127. [3] Compile the program using the UNIX make utility. (i.e. type "make")
  128. [4] Place the 'rasmol' executable on the execution PATH, i.e. /usr/local/bin
  129. [5] Install rasmol.hlp as /usr/local/lib/rasmol/rasmol.hlp (or at a loctaion
  130.     indicated by the environment variable RASMOLPATH).
  131. [6] If you have the UNIX utilities "uncompress" or "gunzip" ensure they are
  132.     on the user's default PATH.
  133. [7] Set the environment variable RASMOLPDBPATH to the directory containing
  134.     the Broohaven PDB database, if one exits.
  135. [8] Place any system wide initialisation parameters into the file "rasmolrc"
  136.     in the directory pointed to by RASMOLPATH.
  137. [9] It is possible to set-up RASMOLPATH and RASMOLPDBPATH each time the 
  138.     program is running by renaming rasmol to rasmol.exe, and using a script
  139.     similar to the one in "rasmol.sh" of the standard distribution.
  140. [10] If appropriate place "rasmol.1" or "rasmol.0" in the appropriate place
  141.      for UNIX man pages, and optionally place "rasmol.html" somewhere in 
  142.      your WWW hierarchy (if available at your site).
  143.  
  144.  
  145. MS Windows v3.1:
  146. ----------------
  147. [1] Copy both the executable RASWIN.EXE, RASMOL.HLP and RASWIN.HLP to an
  148.     appropriate directory.
  149. [2] Install the program in MS Windows using the New option of the Program
  150.     Manager's File Menu. Set the Description of the Program to "RasWin v2.6"
  151.     and the Current Directory, to the directory containing the files.
  152. [3] Install the RasMol Help file using the New option of the Program
  153.     Manager's File Menu. Set the Description to "RasWin Manual", the
  154.     command to "C:\WINDOWS\WINHELP RASWIN.HLP" and the working directory
  155.     to the appropriate directory.
  156.  
  157. MS Windows NT, Windows 95 and Win32S:
  158. ------------------------------------
  159. [1] Copy both the executable RASWIN32.EXE, RASMOL.HLP and RASWIN.HLP to an
  160.     appropriate directory.
  161. [2] Install the program in MS Windows using the New option of the Program
  162.     Manager's File Menu. Set the Description of the Program to "RasWin32 v2.6"
  163.     and the Current Directory, to the directory containing the files.
  164. [3] Install the RasMol Help file using the New option of the Program
  165.     Manager's File Menu. Set the Description to "RasWin Manual", the
  166.     command to "C:\WINDOWS\WINHELP RASWIN.HLP" and the working directory
  167.     to the appropriate directory.
  168.  
  169.  
  170. Macintosh and PowerMac
  171. -----------------------
  172. [1]  Place both "RasMac v2.6" and "rasmol.hlp" in the same Macintosh folder
  173.  
  174. VAX/VMS
  175. -------
  176. [1] Modify the #defines in the file rasmol.h (see below)
  177.         Note: IBMPC, MITSHM and TERMIOS should not be defined.
  178. [2] Copy all the files from the "vms" directory to the source directory.
  179. [2] If your VAX site has an MMS license type the command "MMS",
  180.     otherwise use the DCL build script by typing "@build.com"
  181. [3] The program may be run by typing "RUN RASMOL.EXE", the X Windows
  182.     server is specified by a VMS command of the form:
  183.     SET DISPLAY/CREATE/TRANSPORT=TCPIP/NODE=<hostname>
  184. [4] The symbol should be defined the the path of RASMOL.EXE using :==
  185. [5] The file rasmol.vms contains a ascii VMS help file that can
  186.     be compiled in to the VMS on-line help system.
  187.  
  188.  
  189. [3] Recompiling RasMol v2.6
  190. ===========================
  191.  
  192. MS Windows v3.1:
  193. ----------------
  194. [1] Use Makefile.pc instead of Makefile, by copying it to MAKEFILE.
  195. [2] Modify the contents of the Makefile to determine your local C compiler,
  196.     compiler and linker options. 
  197. [3] Modify the #defines in the file rasmol.h (see below)
  198.         Note: EIGHTBIT and IBMPC should all be defined
  199.               APPLEMAC, DIALBOX, MITSHM and TERMIOS should not be defined.
  200. [4] Compile the program using the Microsoft Optimizing C Compiler Version
  201.     7's (or Microsoft Visual C++'s) NMAKE program under MS-DOS.
  202.  
  203. MS Windows NT
  204. -------------
  205. [1] Using Microsoft Visual C++, create a new project adding all the
  206.     "*.c" source files except "rasmol.c", "x11win.c", "rasmac.c" and
  207.     "applemac.c". Add the Windows resource source file "raswin.rc".
  208.     or alternatively use Makefile.nt by copying it to MAKEFILE.
  209. [2] Follow the instructions from [2] onwards as for MS Windows v3.1.
  210.  
  211. Apple Macintosh and PowerMac
  212. ----------------------------
  213. [1] Create a project in either the Symmantec C/C++, Think C or Metrowerks 
  214.     C compiler environments and add all the C source files ("*.c") to 
  215.     the project. On 68k development systems all C files should be placed
  216.     in separate segments [however rasmac.c and applemac.c can share a
  217.     segment and abstree.c and command.c can share a segment].
  218. [2] Add the "rasmac.rsrc" resource file to the project.
  219. [3] For the Symantec/Think C environment add the "ANSI" or "ANSI-small"
  220.     library from "Standard Libraries" folder and the "MacTraps" library
  221.     from the "Mac Libraries" folder. The choice of "ANSI" or "ANSI-small"
  222.     is dependent upon the size of integer by the compiler. See dialog
  223.     'Edit'->'Options'->'Think C..'->'Compiler Settings'.  2-byte integers 
  224.     require "ANSI-small" and 4-byte integers require "ANSI".
  225. [4] For the Metrowerks 68K Compiler add the libraries "MacOS.lib" and
  226.     "ANSI (2i) C.68K.Lib" to the project. [Note: If compiling for 4byte 
  227.     integer size and/or 68881 maths instructions select the approriate 
  228.     ANSI C Library].
  229. [5] For the Metrowerks PPC Compiler add the libraries "MWCRuntime.Lib",
  230.     "InterfaceLib", "MathLib" and "ANSI C.PPC.Lib". This should work
  231.     fine for Metrowerks C++ v1.1.  Apparently, Metrowerks C++ v1.2 also
  232.     requires "console.stubs.c". [Thanks to Graham Palmer]
  233. [6] In Metrowerk's "Edit" "Preferences" "Project" or Symmantec's "Project"
  234.     "Set Project Type", set the project type to Application (Type 'APPL'), 
  235.     Creator 'RSML', and the SIZE flags to include "is32bitCompatible", 
  236.     "isHighLevelEventAware", "localAndRemoteHLEvents".
  237. [7] Modify the #defines in the file "rasmol.h" (see below).
  238.         Note: APPLEMAC should all be defined
  239.               IBMPC, DIALBOX, MITSHM and TERMIOS should not be defined.
  240. [8] Compile RasMol using the "Build Application..." Menu Item.
  241. [9] To create a `fat' binary, use Apple's ResEdit to copy and paste the
  242.     CODE, DATA and XREF resources from the Metrowerks 68K executable 
  243.     into the resource fork of the Metrowerks PPC executable.
  244. [10] The Installed Application's name should be "RasMac v2.6"
  245.  
  246.  
  247. COMPILATION DIRECTIVES
  248. ======================
  249.  
  250. The file rasmol.h contains a number of #define directives that control
  251. the runtime behaviour of the program. The following directives may be
  252. defined or undefined to suite the local site.
  253.  
  254. THIRTYTWOBIT
  255. EIGHTBIT    This determines whether RasMol will display and produce
  256.         8bit or 32(24) bit output. By default this symbol is defined
  257.         producing images with up to 256 colours. This symbol must 
  258.                 be defined if IBMPC is defined.
  259.  
  260. DIALBOX        This enables the use of a dials box, that is connected 
  261.         using the X Window System XInput extension. This option
  262.         requires that the program be compiled with the Xi and
  263.         Xext libraries. Note: libXi is called libXinput on some old
  264.         machines, so requires the compiler option -lXinput!
  265.  
  266. MITSHM         This option enables the use of the X Window System MIT shared
  267.         memory extension. This enables images to be displayed faster
  268.         when RasMol and the X11 server are running on the same host.
  269.         This option requires the program be compiled with the Xext
  270.         library. On IBM RS6000s runnning AIX, MITSHM also requires
  271.                 the XextSam library (which requires changing the Makefile or
  272.                 Imakefile). This is now enabled by default. This should be
  273.                 disabled on E&S ESV workstations as MITSHM support is not 
  274.                 provided as standard.
  275.  
  276. TERMIOS        This directive enables the command line processing on UNIXs
  277.         that support the termios terminal handling routines. By 
  278.         leaving this symbol undefined, RasMol omits the interactive
  279.         command line interface. Undefining is not recommended!
  280.  
  281. APPLEMAC        This determines whether the program is to run on an Apple
  282.                 Macintosh or PowerMac. By default, this option is disabled.
  283.                 The Macintosh code may be compiled to be either EIGHTTBIT
  284.                 or THIRTYTWOBIT and will generate images effectively.
  285.  
  286. IBMPC           This determines whether the program is intended to run on an
  287.                 IBM PC or compatible under MS Windows. By default, this 
  288.                 option is disabled. If this option is defined the options 
  289.                 EIGHTBIT and INVERT must be defined, and TERMIOS undefined.
  290.  
  291. To summarise;
  292.     A typical UNIX build:
  293.         /* define IBMPC    */
  294.         /* define APPLEMAC */
  295.         /* define DIALBOX  */
  296.         #define TERMIOS
  297.         #define MITSHM
  298.         #define EIGHTBIT
  299.  
  300.     A typical Windows build:
  301.         #define IBMPC
  302.         /* define APPLEMAC */
  303.         /* define DIALBOX  */
  304.         /* define TERMIOS  */
  305.         /* define MITSHM   */
  306.         #define EIGHTBIT
  307.  
  308.     A typical Macintosh build:
  309.         /* define IBMPC    */
  310.         #define APPLEMAC
  311.         /* define APPLEMAC */
  312.         /* define DIALBOX  */
  313.         /* define TERMIOS  */
  314.         /* define MITSHM   */
  315.         #define EIGHTBIT
  316.         
  317.     A typical VMS build:
  318.         /* define IBMPC    */
  319.         /* define APPLEMAC */
  320.         /* define DIALBOX  */
  321.         /* define TERMIOS  */
  322.         /* define MITSHM   */
  323.         #define EIGHTBIT
  324.  
  325. Roger
  326. -- 
  327. Roger Sayle                                INTERNET:  ras32425@ggr.co.uk
  328. Glaxo Wellcome Medicines Research Centre,             rasmol@ggr.co.uk
  329. Gunnels Wood Road, Stevenage,        Tel:   +44 (0)1438 763246 (direct line)
  330. Hertfordshire, SG1 2NY, U.K.         Fax:   +44 (0)1438 763082
  331.