Adding Modules
Introduction
Section describes the procedures to be followed when adding new modules to ChemShell.
It is assumed that you have already written the Tcl and C/Fortran
code required to implement the new module.
The stages, described in more detail below are:
- Create a new subdirectory to hold the source code files.
- Create the Makefiles to build the code in a machine independent manner
- Define the interface using the CHEMSH_INTERFACE file
- Optionally control whether the module is activated, using the CHEMSH_SWITCH file
Create the subdirectory
The code should reside in a subdirectory of the chemsh/src directory
of the distribution. This directory will hold both Tcl files, source
code and object code.
Makefiles and machine dependencies
2 makefiles -
makefile
makefile which should always have the following structure,
is the same for all modules.
#
# this makefile will be used by make in preference to Makefile
# Together with ../make.master its function is to create a real
# Makefile from Makefile.mk (if required) and then to pass any
# targets/options etc to it.
#
# all changes should be made to Makefile.mk
#
all:
@$(MAKE) -f ../make.master $(MAKEOPTS)
Makefile: Makefile.mk
@$(MAKE) -f ../make.master Makefile
.DEFAULT:
@$(MAKE) -f ../make.master $(MAKEOPTS) $@
The purpose is to pass control when the command make is issued to the
makefile make.master in the directory chemsh/src. This in turn checks
that the main makefile (which will be called Makefile is
present. If it is not, it is generated by preprocessing from the file
Makefile.mk, which must be provided.
Makefile.mk
This file, after preprocessing will control compilation and in general
will build a library for linkage into ChemShell.
The following example is used to build a library for the GAMESS-UK
interface (it has been slightly simplified) :
#
# build the GAMESS-UK interface library
#
#include ../compilerflags.mk#
#endinclude ../compilerflags.mk#
LIB1=../../lib/libgamess_interface1.a
OBJ1 = interface.o
all: $(LIB1)
$(LIB1): $(OBJ1)
rm -f $(LIB1)
$(ARCHIVE) $(LIB1) $(OBJ1)
$(RANLIB) $(LIB1)
.f.o:
$(FC) -c $(FFLAGS) $*.f
.c.o:
$(CC) -c $(CFLAGS) $*.c
clean:
touch x.o x~ \#x
rm -f *.o *~ \#* a.out ARCH $(LIB1)
Note the following features:
- the #include.....# and #endinclude....# constructucts that will cause the
contents of the file ../compilerflags.mk to be inserted at this point
- the use of sumbols such as $(CC), $(FC), $(ARCHIVE) etc that will be defined
in ../compilerflags.mk.
- The clean target, that removes the target library, and also the file ARCH (a stamp file used
to denote the current build architecture.
On typing make, the file Makefile is first generated, and then the library is
compiled using th rules contained within it. Not that Makefile will be
rebuilt automatically every time Makefile.mk is modified.
The CHEMSH_INTERFACE File
This file controls the linkage between the new module and the main program
of ChemShell. The corresponding example for the GAMESS-UK interface is
as follows:
#
# this file defines the interface between
# chemshell and GAMESS-UK
#
MODULENAME gamess
LIBRARY libgamess_interface1.a 1
DECLARATION declare_gamess1
TCLFILE gamess.tcl
PATHAPPEND /usr2/psh/GAMESS-UK/scripts
MODULENAME specifes a name - used in diagnostic messages only.
LIBRARY specifes the name of a library that must be included
in the loading of ChemShell binary.
DECLARATION specifes the name of a C-callable function that must be
called during the initialisation of ChemShell to perform any functions required.
In general, the function will simply create the new commands needed in the Tcl
interpreter required for the module.
TCLFILE specifes the name of a Tcl source file in the module
directory that contains code needed for the module.
PATHAPPEND specifes a directory name to append to the executable
path when ChemShell runs.
The CHEMSH_SWITCH Script
This executable file is optional. It should exit with a return code of 1
if the inclusion of the module is to be suppressed, and a code of 0 if
the module is to be included. It could, for example check the availability
of an executable program on the system, or make a decision based on
the architecture on which the code is being compiled. If absent the module
will be included.
Reconfiguring ChemShell to include the new module
After a version of the code has been included, the command
% make config
issued in the chemsh/src/chemsh directory will parse the CHEMSH_INTERFACE
file. Subsequently typing make will compile ChemShell with the new module.
|
