TWIST MOFIA MANUAL

Using CVS and Installing and Compiling Mofia.


CVS:

CVS is the version control system used for the TWIST software. CVS
allows us to save the different versions of a source file, tag the
source code to create a version of MOFIA when desired, and keep track
of differences between the different versions of a file, as well as
differences between files in the user's development directories and
those in the CVS repository. The contents of the TWIST CVS code can be
viewed on the web at

http://twist.triumf.ca/cgi-bin/cvsweb.cgi

A detailed discussion of CVS as well as a detailed description of its
commands may be found in the CVS manual. The following is a short list
of the most commonly used CVS commands for easy reference.

The TWIST Software Installation Guide

  http://twist.triumf.ca/private/offline/install.html

has convenient step-by-step instructions for installing and compiling
everything from scratch.  See there for the most recent
recommendations.

The command

cvs checkout argument

may be used to checkout a file or a directory. It may also be used
with qualifiers to specify the version number of the code to be
checked out and the directory it should be placed in. For example, the
command

cvs checkout -d devel MOFIA-2-2 mofia

will create a subdirectory called "2.2" and place revision "MOFIA-2-2"
of the "mofia" code inside it. This code will include all the
directories of the MOFIA source code and their contents.

The command

cvs status filename

displays the status of a specific file. If the filename is omitted the
status of all the files in the directory in which the command is
entered are displayed. The user might often wish to check the status
of only the files that differ from CVS in that particular
directory. In this case the command

cvs status | grep -i need

is handy. This will pipe the cvs status command through the grep
command to search for the files that need to be updated or committed
(see below).

cvs update filename

This command allows the user to update their source code with new code
from CVS. When no filename is specified, code in the entire directory
in which the command is issued will be updated. If the user has
modified files in his/her own directory, the CVS code will be merged
with the user's code. In some cases conflicts may occur in which case
CVS will prompt the user. In such cases the user has to edit the file
and resolve the conflicts by hand. Conflict sections are labeled by
CVS with a ">>>>" and "<<<<". Care must therefore be taken when using
this command. In some cases users may want to save their modified
files under a different name before updating from CVS in case they
need to check differences, etc. The cvs update command lists the
filenames in which differences are found as well as the code that
differs for the user to make comparisons. It is often convenient to
only list the filenames containing differences only (without
displaying any code). This is achieved by using a qualifier

cvs update --brief

Notice that there are two "-" signs preceding "brief"!

The Command

 cvs commit filename

Is used to commit files to the CVS repository. The command will prompt
the user to type in a description of the modifications made to the
file. The editor defined by the environment variable CVSEDITOR is
invoked for this purpose. The user may therefore find it handy to set
this environment variable to his/her editor of choice in their own
.login file. For example to have CVS invoke the emacs editor when
using the cvs commit command, the following line would be needed to be
entered prior to using the commit command (or better yet added to the
user's own .login file)

setenv CVSEDITOR emacs

The cvs commit command will only allow the user to commit files that
already exist in the CVS repository. If the a new file is to be added
to the repository the command

cvs add filename

Should precede the cvs commit command.

Files may also be removed from the CVS repository using the command

cvs remove filename

Followed by

cvs commit filename

All the above commands are best understood when they are tried.

A good CVS manual may be found on the web at

http://cvsbook.red-bean.com/


Installing and Compiling MOFIA

All the MOFIA source code as well the setup files are committed to
cvs. In order to have access to CVS, the user needs to be a member of
the e614cvs group.  This allows the user to checkout the MOFIA
code. Detailed step-by-step instructions on installing MOFIA are
posted on the web at

http://twist.triumf.ca/private/offline/install.html


1 Compiling MOFIA

Each of the subdirectories: main, mainf90, dummy, and photo has its
own Makefile. When the make file is executed, a library corresponding
to this subdirectory is created (or updated) and placed in the
directory mofia/2.2/lib. The corresponding libraries are libmain.a,
libmainf90.a, libdummy.a, and libphoto.a. Notice that the include
files used by code in any of these subdirectories resides in the
include subdirectory, and similarly the .mod files created when
compiling code in any of these subdirectories resides in the modules
subdirectory. In contrast, when the Makefile in the user subdirectory
is executed, the .mod and .o files remain in the user subdirectory (no
libraries are created).

Scripts are available to build MOFIA. These may be found in the directory

?/e614soft/triumf/mofia/2.2

for the MOFIA 2.2 version. In particular, the script make_all allows
the user to build MOFIA from scratch. To do so, simply execute the
command

make_all

Once MOFIA is built from scratch once, the user will only need to
execute the make command in the directory where modifications have
been made and the subsequent directories (which contain code that
depends on these modifications). Often, the user will be modifying
code only in the user subdirectory in which case only code in the user
subdirectory needs to be compiled.

When compiling MOFIA (in the user subdirectory) the user has the
option of making any of three different executables: plain, mofia or
photo. The first executable, plain, does not contain any code from the
mainf90, user, or photo subdirectories. The second executable, mofia,
contains all of the MOFIA code except for the event display (photo
subdirectory). The last executable, photo, contains the entire
code. To make any of these three executables the user needs to issue
the command "gmake executable" where "executable" stands for plain,
mofia or photo. For example,

make photo

makes the photo executable. If only the gmake command is issued (with
no executable name) all three: plain, mofia and photo will be made and
placed in the user subdirectory.

2 Compiling a debug Version 

The libraries corresponding to main, mainf90, dummy and photo in
mofia/2.2/lib are all compiled with the debug flag off to allow faster
execution. Since debug information may be needed at times, a debug
version of all these libraries is provided in the subdirectory
mofia/2.2/debug. The default libraries are the non-debug ones, so that
the environment variable MOFIA_LIBDIR is assigned to mofia/2.2/lib by
default, and the debug flag is turned off when the code in the user
subdirectory is compiled. To compile a debug version of MOFIA the user
needs to issue the command

mlib f90 debug

Before compiling. This will assign the environment variable
MOFIA_LIBDIR to mofia/2.2/debug and turn the debug flag on when
compiling the mymofia code. If the user wishes to go back and
recompile a non-debug version, the command

mlib f90

must be issued before executing the Makefile.

3 Module Dependencies

It would be inefficient to recompile all the code whenever a file is
modified in one of the source subdirectories. On the other hand,
compiling only the file modified will not be sufficient in some cases
since other files might depend on it. For example, if module A is
changed, one needs to find all the modules and procedures that USE
module A and recompile them. This is also true when any of the include
files is changed. In each of the subdirectories main, mainf90, dummy
and photo, a file called Dependencies is supplied to serve this
purpose. This file contains a list of modules and includes files that
a .o file "depends on" so that if any of these files is changed the
.f90 (or .F) file corresponding to this .o file is recompiled. This
information is made available by inserting the statement "include
Dependencies" in every Makefile in the source subdirectories.

The Dependencies file itself is created by executing the script
depend_f90.csh (which resides in the directory defined by the
environment variable TRIUMF_ROOT) from the source subdirectory in
which the dependencies are to be found. This script goes through every
file in this subdirectory and extracts all filenames that this file
depends on (by examining all the USE and INCLUDE statements in that
file).

It is important to remember that the list of object files in the
Makefile has to be constructed in such a way so that the dependent
files come after those they depend on.

Problems are sometimes encountered when compiling code only in a
specific MOFIA subdirectory. While the origin of these compiling
problems is not understood, it is found to be related to file
dependency issues. If the user runs into compiling problems or runtime
errors after only compiling code in a specific MOFIA subdirectory, the
user can try to rebuild MOFIA from scratch using the make_all command
discussed above.