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.