Installation

The installation procedure for v2.1 has been simplified compared to v2.0. The directory structure of the distribution has changed.

Now, only one single make command is needed to create the executables. It is, however, still necessary to choose which Makefile to use, and possibly to edit the Makefile. This is because some output modes require external software. However, the basic implementation of MolScript (with the PostScript, Raster3D and VRML 2.0 output modes) needs no external software, and is straightforward to compile.

This description assumes that you have a UNIX computer system. The installation procedure has been tested (so far) only on an SGI IRIX 6.3 system, but should work on other UNIX systems as well.

Information on other computer systems is currently not available, but it shouldn't be too difficult to install MolScript if you know how to compile programs on your computer system. If you port MolScript to another system, you would help others by sending a description of your porting procedure to pjk@avatar.se. The description will be incorporated into this documentation.

The distribution

You will have obtained the MolScript distribution by downloading via Netscape's " Shift + left-mouse-button" function. It comes in two possible forms:
molscript.tar.Z
compressed using the standard UNIX compress utility program.

molscript.tar.gz
compressed using GNU's gzip program.
The file is a compressed tar file, that is, the directories in the distribution have been bundled together using the standard UNIX tar utility program, and the resulting tar file was subsequently compressed with either compress or gzip.

Save previous MolScript versions

The previous versions of MolScript must not be mixed with the current distribution.

Before unpacking the current distribution, move your previous MolScript distribution (if you have one) to some safe location. This applies to the molscript directory, as well as the previous molscript and molauto executable files.

Unpacking the distribution file

First, uncompress the distribution tar file using one of the following commands:
% gunzip molscript.tar.gz
or
% uncompress molscript.tar.Z
This produces a molscript.tar file. This file should be moved to the directory where you wish to have the molscript source directory located. For example, the /usr/local directory is often used for software of this kind. You probably need root privileges (or the equivalent) to write anything in the /usr/local directory.
% mv molscript.tar /usr/local
% cd /usr/local
 Then use the tar program to unpack the distribution:
% tar xvof molscript.tar
This creates the molscript directory and its subdirectories.

Directory structure of the distribution

The MolScript distribution contains the following directories:
molscript
The top directory, containing the C source code for the MolScript and MolAuto programs. Two different Makefiles are provided to build the programs.

molscript/clib
The C source code for general-purpose routines and data structures used in the MolScript source code.

molscript/other
Source code written by other people, and used directly in the MolScript source code. The copyright statements covering this software is given here.

molscript/doc
This documentation in HTML format.

molscript/doc/images
The image files for this documentation.

molscript/examples
A set of example input files, with the PDB coordinate file these input files use, and a Makefile.

External software libraries

It is possible to compile a basic implementation of MolScript, which needs nothing more than the source code that is included in the distribution. However, this will only enable a subset of the available output modes.

The complete implementation of MolScript requires some additional external software and system libraries. You must fetch and install these libraries yourself.

It is possible to compile partial implementations, if only some of the external software libraries are available. For instance, it is possible to compile MolScript to produce GIF image files, without having the PNG image file capability.

Note: Although GNU's bison program is needed to convert the molscript.y file into C source code, it is not necessary for compiling the programs; the C source code files are included in the distribution.

The software requirements for the different output modes.
Output mode Required system libraries Required external software
PostScript none none
Raster3D none none
VRML 2.0 none none
Interactive OpenGL OpenGL (or Mesa) GLUT library
SGI (aka RGB) image file OpenGL (or Mesa) and
X windows (implies UNIX) 		GLUT library
Encapsulated PostScript
(EPS) image file 		OpenGL (or Mesa) and
X windows (implies UNIX) 		GLUT library
JPEG image file OpenGL (or Mesa) and
X windows (implies UNIX) 		GLUT library and
JPEG library
PNG image file OpenGL (or Mesa) and
X windows (implies UNIX) 		GLUT library and
PNG and zlib libraries
GIF image file OpenGL (or Mesa) and
X windows (implies UNIX) 		GLUT library and
gd 1.3 library

Notes

  1. Mesa is a free, non-official, software-only implementation of the OpenGLlibrary, which may be used if a native OpenGL library is not available in your system.

The Makefiles

There are two different Makefiles in the molscript directory. Both have been tested on an SGI IRIX 6.3 system. They should work (possibly with minor changes) on other UNIX systems.

Makefile.basic
This will build the basic implementation of MolScript, which will produce only the PostScript, Raster3D, and VRML 2.0 output files. No external software libraries are needed. As distributed, the Makefile will use GNU's gcc compiler.

Makefile.complete
This will build the complete implementation of MolScript, including support for the interactive OpenGL graphics mode, and all image file output formats. As distributed, the Makefile will use SGI IRIX's native cc compiler.

Several external libraries are required for the complete implementation; see the table above. You must make sure that the various symbols in the Makefile.complete file are set correctly. If you do not wish to include a certain image file format implementation, then you must comment out all symbol definitions in the Makefile.complete which relate to that format.

You must choose which of these Makefiles to use. You can either make a symbolic link to the appropriate Makefile variant (the basic one in this example):

% ln -s Makefile.basic Makefile
or you can make a proper copy of the chosen Makefile variant:
% cp Makefile.basic Makefile

The Makefiles contain various symbols which may need to be modified for your system. For instance, the location of the external libraries must be defined, and the optimization flags for the C compiler you are using must be set correctly.

Note that for the SGI IRIX cc compiler, it is necessary to choose the type of object file by specifying one of the following flags: -32, -64 or -n32. It is not possible to mix object files compiled using different flags. The external libraries (if used) must also have been compiled with the same flag.

Notes

  1. It should be possible to compile the OpenGL implementation on a Windows 95 or a Windows NT system, since the GLUT library has been implemented for these systems. However, this has not yet been tested.

  2. All image output formats require the OpenGL implementation. Currently, they also require the X window system having the GLX extension required for OpenGL. This implies that the computer system must be a UNIX machine. Currently, the image output formats cannot be compiled on Win95 or WinNT. If you do not have the OpenGL libraries, or your system does not have the X window system with the GLX extension, then it is not possible to compile any of the image file format output implementations.

  3. The SGI and EPS image formats require OpenGL and the X window system, but no other external libraries.

  4. The Makefile.complete file is written under the assumption that the external libraries are all in object archive format (*.a files). Your copy of the library may not have been installed in this form. Either modify the Makefile.complete file, or create the *.a files according to the instructions for each library.

Compiling the software

If you made a copy of, or linked to (see above) the appropriate Makefile variant and modified it (if needed) and installed the various external libraries (if any), then you should be ready to compile the MolScript program.

Go to the molscript directory and give the following command:

% cd /usr/local/molscript
% make
This will compile the source code in the molscript and molscript/clib directories, and link together the molscript and molauto executable files in the molscript directory.

The clib.a object code archive is compiled automatically by this command, in contrast to the previous v2.0 distribution, where this was a separate command. Indeed, it is not possible to use the Makefile in the molscript/clib directory on its own: it must be called indirectly from the Makefile in the main molscript directory.

You may wish to copy the executables to an appropriate directory on your system (such as /usr/local/bin):

% cp molscript molauto /usr/local/bin
or make links from that directory to the executables:
% cd /usr/local/bin
% ln -s /usr/local/molscript/molscript molscript
% ln -s /usr/local/molscript/molauto molauto
You and any other users need to have this directory in their path if the executable is to be invoked simply by giving the program name as a command. Check that the PATH environment variable contains the /usr/local/bin value:
% echo $PATH

Rendering the example files

There is a Makefile in the molscript/examples directory, which can be used to render all example input files. The Makefile contains a few symbols that may have to be changed; it should be fairly clear in the file which these are.

If the complete implementation has been compiled (all output modes present), then give the command:

% make complete
This will run MolScript and any other programs to create the example files referred to in the documentation.

If the basic implementation has been compiled, then give the command:

% make basic
This will create only the PostScript, Raster3D and VRML 2.0 files.

Top page