Forgot your password?
New user?
Views
Editing cm source
Introduction
CMISS is managed under CVS (Concurrent Versions System). CVS allows source files to be stored in repositories with programmers `checking out' files to make changes.
This allows many people to make changes to a file at a time, and programmers can test their development by compiling a local version of CMISS.
Local and global versions of cm
Each programmer has their own `local' working directory (or possibly working directories if working on more than one modification concurrently) in which they can checkout from the CVS repository source code files that they wish to work on. The programmer can then build their own `local' cm executable, which contains their changes and they can run, test, and debug.
When programmers commit their changes to the CVS repository, the `global' source is automatically updated on various platforms. In the Bioengineering Institute, this global source is usually under the directory /hpc/cmiss, which is usually the home directory of the user cmiss. No changes should be made directly to the global source.
The global source is used to build the global versions of CMISS, and may also be used by individual programmers when the corresponding files have not been checked out in their local working directory.
Editing CMISS source
All cm source modules are visible in the global source directories, but CVS must be used to check out working copies before any editing is done. While developing in a working directory, changes in the global version can be automatically merged and the developer warned of conflicting changes made by simultaneous developers. This should be done often enough to maintain consistency (in procedure names and arguments and common blocks, etc.) between local and global versions and to detect at the earliest opportunity any possibly conflicting changes others are making. When the local version has been thoroughly tested, the changes can be commited to the CVS repository. This process is described in a brief introduction to CVS.
Initial Setup
To set yourself up to develop CMISS under Unix, there are a few of steps to take.
Environment variables
Using an editor (such as vi or emacs), edit the .tcshrc or .cshrc file in your home directory.
ie emacs $HOME/.cshrc
Set the root path for cmiss and the location of the CVS repository by adding
setenv CMISS_ROOT /hpc/cmiss
Beneath these lines, you may like to add 'source $CMISS_ROOT/cmiss_utils/scripts/cmiss_programmer.sh', which will set up many CMISS variables and aliases, most of which you will not use. It is probably better to just copy appropriate lines to set up the variables and aliases that you want, if you want any.
Setup for CVS
Read Setting Up for CMISS CVS Access and follow the instructions there.
Local cm directory structure
First change to the directory where you want to create your local cm development directory. Then checkout the Makefile from $CMISS_ROOT/cm into the development directory and the source files you intend to edit into a source subdirectory. e.g.
cvs checkout cm/Makefile cm/make cm/source/fe11.f cm/source/fe20.f
or
cvs checkout -d mycm cm/Makefile
cd mycm
cvs checkout -d source cm/source/fe11.f
cd source
cvs update fe20.f
Local cm
Compiling and linking a local cm
Change directory to your local development directory, and run gmake. e.g.
cd $HOME/mycm
gmake
or let gmake change directory for you. e.g.
gmake -C $HOME/mycm
A generated directory will be created for the object files, dependency files, and preprocessed fortran files, and a dso directory for the executable and the dynamic shared objects (DSOs) which are dynamically linked into the executable at run time.
The executable will be made using the local modules in the source directory. The modules not found in source are taken from the global CMISS directory as indicated by the CMISS_ROOT environment variable.
If you want an executable without any DSOs then supply the option STATIC= to the gmake command. The executable will be created in a bin directory and may have a different name to the dynamic version.
Run
gmake help
for information on making different versions of cm.
Running a local cm
Run the local cm executable by typing the path to the executable. e.g.
$HOME/mycm/dso/mips3-n32-debug/cm arguments
You may like to set up aliases for these commands in your .(t)cshrc file. (See man csh or man alias.)
Debugging
Debug the local cm executable with a command such as
cvd $HOME/mycm/dso/mips3-n32-debug/cm &
Help on this is available through the irix command insight in the book ProDev WorkShop: Debugger User's Guide.
Global cm
Compling and linking a global cm
Note that currently it is not possible for general users to write to the global CMISS objects or executable. Therefore, in order to update the global cm, it is first necessary to login as (or su) cmiss. When developing, it is helpful to keep one window logged in as cmiss at all times.
Compiling a global cm is the same as compiling a local version. Either
cd $CMISS_ROOT/cm
gmake
or
gmake -C $CMISS_ROOT/mycm
The alias cmmake is set up in cmiss_programmer.sh to change to the appropriate directory for you. So you can just
cmmake
On hpc*, this alias will also ensure that the source is the latest version in the CVS repository before running the Makefile.
The static versions of cm are made nightly and should not usually be remade during the day as someone may be running the executable, so please don't specify the STATIC= variable on the make command unless you have a good reason to overwrite the executable. If you need a static executable for the latest source, then you can make a static local version.
Further help on compiling other versions and usage of the Makefile can be obtained using
cmmake help
Running a global cm
Running a global cm is the same as running a local version. Run the global cm executable by typing the path to the executable. e.g.
$CMISS_ROOT/cm/bin/mips3-n32/cm-debug arguments
or supply the path to the executable as an argument to cvd to debug the executable.
This executable is made nightly. If your program is still running when the executable is remade it will crash. If you want to run an executable over night you should make a copy.
Many of the executables in $CMISS_ROOT/bin are links to these nightly-made executables. If $CMISS_ROOT/bin is in your PATH environment variable then you don't need to type the full path to run the executable (but you still need to supply the full path to cvd).
If you have sourced $CMISS_ROOT/cmiss_utils/scripts/cmiss_programmer.sh then the following aliases may be available:
cm - runs the 32 bit version of CMISS
cmd - runs the 32 bit debug version of CMISS
cm_mp - runs the 32 bit multiprocessing version of CMISS
cm_mpd runs the 32 bit multiprocessing debug version of CMISS
cmo - runs the 32 bit optimised version of CMISS
cmod - runs the 32 bit optimised debug version of CMISS
cmo_mp - runs the 32 bit optimised multiprocesing version of CMISS
cmo_mpd - runs the 32 bit optimised multiprocesing debug version of CMISS
cm64 - runs the 64 bit version of CMISS
cmd64 - runs the 64 bit debug version of CMISS
cm64_mp - runs the 64 bit multiprocessing version of CMISS
cm64_mpd - runs the 64 bit multiprocessing debug version of CMISS
cmo64 - runs the 64 bit optimised version of CMISS
cmod64 - runs the 64 bit optimised debug version of CMISS
cmo64_mp - runs the 64 bit optimised multiprocesing version of CMISS
cmo64_mpd - runs the 64 bit optimised multiprocesing debug version of CMISS
Dynamic Shared Objects
If you use dynamic shared objects (DSOs) for your local CMISS, it is not necessary to relink all of your local CMISS each time you make a change. Only the module or routine that is changed needs to be compiled and linked. This can speed up things immensely if you are making small changes often and want to test the modifications.
What follows is some possibly outdated information that might enable you to get DSOs working.
Dynamic Linking Basics
Before doing any linking, a copy of /usr/lib32/so_locations should be made. It's probably best to place this in the same directory as where the dynamic shared objects (DSOs) are going to be placed. This is not essential but means that when DSOs are linked, they can be assigned a location in memory that doesn't conflict with any other DSOs that may be used. If there is a conflict then addresses are shifted by the run-time linker anyway.
Compiling is done the same as for with static linking.
Linking is done in two stages.
Stage 1: Producing the DSOs
This is done with a command like
ld -shared -n32 -mips3 -update_registry ${DSO_DIR}/so_locations <object-list> -o <dso-name>
-shared indicates that the output is a shareable object.
<object-list> can be one or many modules.
If there is an error allocating memory locations suggesting to check your so_locations file, then edit the file to clean out DSOs that will not be used by the final executable. This'll free up some space. More space can be made available by increasing the $startaddress value.
I don't think it's worth trying to include any statically linked libraries at this stage.
Stage 2: Producing the Executable
Objects, DSOs, and static libraries are linked using something like
f77 -n32 -mips3 -ignore_unresolved -rpath ${DSO_DIR} <object/DSO-list> <library-specifiers> -o <executable-name>
-ignore_unresolved may be unnecessary
-rpath ${DSO_DIR} is to let the run-time linker know where to look for the DSOs.
<object/DSO-list> can include both object files and DSOs. I have only DSOs and have a DSO for each module. You may like to have one DSO for most of the modules and a few for the ones you're going to change. It is also possible to link most modules directly into the executable and just have DSOs for the modules you're changing. There doesn't seem to be much advantage in these alternative approaches but the debugger may be less likely to get confused. I found that step-into often worked like step-over if the intended routine to step into was in another DSO. I got around this by setting breakpoints at routine entries. Also the debugger often could not view arrays. I never had this problem if I was viewing the first DSO in the link list, so I got around this by including routines in the first DSO (see below).
<library-specifiers> are for static libraries.
This stage does not need to be done very often at all. The executable knows only about the names and where it might find its DSOs. It doesn't know what symbols are in each module. That is sorted out at run-time. A new executable will need to be made if the module list changes or if a static library changes. Another time when it'll need to be redone is if one DSO wants to call a routine from the static library that hasn't been needed before.
Some extra things that should be in this document:
- Guide to debugging using CVD with CMISS - quick fixes to trap common errors.