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:

  1. Create a new subdirectory to hold the source code files.
  2. Create the Makefiles to build the code in a machine independent manner
  3. Define the interface using the CHEMSH_INTERFACE file
  4. 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.

This manual was generated using htp, an HTML pre-processor Powered by htp