Editing cm source

<ul><li><a name="tex2html4" href="#SECTION00020000000000000000">Introduction</a> <ul><li><a name="tex2html5" href="#SECTION00021000000000000000">Local and global versions of cm</a> </li></ul> </li><li><a name="tex2html6" href="#SECTION00030000000000000000">Editing CMISS source</a> </li><li><a name="tex2html7" href="#SECTION00040000000000000000">Initial Setup</a> <ul><li><a name="tex2html8" href="#SECTION00041000000000000000">Environment variables</a> </li><li><a href="#SECTION00041500000000000000">Setup for CVS</a> </li><li><a name="tex2html9" href="#SECTION00042000000000000000">Local cm directory structure</a> </li></ul> </li><li><a name="tex2html10" href="#SECTION00050000000000000000">Local cm</a> <ul><li><a name="tex2html11" href="#SECTION00051000000000000000">Compiling and linking a local cm</a> </li><li><a name="tex2html12" href="#SECTION00052000000000000000">Running a local cm</a> </li></ul> </li><li><a name="tex2html13" href="#SECTION00060000000000000000">Debugging</a> </li><li><a name="tex2html14" href="#SECTION00070000000000000000">Global cm</a> <ul><li><a name="tex2html15" href="#SECTION00071000000000000000">Compling and linking a global cm</a> </li><li><a name="tex2html16" href="#SECTION00072000000000000000">Running a global cm</a> </li></ul> </li><li><a name="tex2html17" href="#SECTION00080000000000000000">Dynamic Shared Objects</a> <ul><li><a name="tex2html18" href="#SECTION00081000000000000000">Dynamic Linking Basics</a> </li></ul></li></ul>

<h1><a name="SECTION00020000000000000000"> Introduction</a> </h1>

CMISS is managed under <a name="tex2html1" href="http://www.nongnu.org/cvs/">CVS</a> (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.

<h2><a name="SECTION00021000000000000000"> Local and global versions of cm</a> </h2>

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' <tt>cm</tt> 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 <tt>/hpc/cmiss</tt>, which is usually the home directory of the user <tt>cmiss</tt>. 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.

<h1><a name="SECTION00030000000000000000"> Editing CMISS source</a> </h1>

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 name="tex2html2" href="/cm/wiki/IntroductionToCVS">a brief introduction to CVS</a>.

<h1><a name="SECTION00040000000000000000"> Initial Setup</a> </h1>

To set yourself up to develop CMISS under Unix, there are a few of steps to take.

<h2><a name="SECTION00041000000000000000"> Environment variables</a> </h2>

Using an editor (such as <tt>vi</tt> or <tt>emacs</tt>), edit the

<tt>.tcshrc</tt> or <tt>.cshrc</tt> file in your home directory.

ie <tt>emacs $HOME/.cshrc</tt>

Set the root path for cmiss and the location of the CVS repository by adding

<tt> setenv CMISS_ROOT /hpc/cmiss </tt>

Beneath these lines, you may like to add '<tt>source $CMISS_ROOT/cmiss_utils/scripts/cmiss_programmer.sh</tt>', 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. <h2><a name="SECTION00041500000000000000"> Setup for CVS</a> </h2> Read Setting Up for CMISS CVS Access and follow the instructions there. <h2><a name="SECTION00042000000000000000"> Local cm directory structure</a> </h2>

First change to the directory where you want to create your local cm development directory. Then checkout the <tt>Makefile</tt> from <tt>$CMISS_ROOT/cm</tt> into the development directory and the source files you intend to edit into a <tt>source</tt> subdirectory. e.g.

<tt> cvs checkout cm/Makefile cm/make cm/source/fe11.f cm/source/fe20.f </tt>

or

<tt> cvs checkout -d mycm cm/Makefile cd mycm cvs checkout -d source cm/source/fe11.f cd source cvs update fe20.f </tt>

<h1><a name="SECTION00050000000000000000"> Local cm</a> </h1>

<h2><a name="SECTION00051000000000000000"> Compiling and linking a local cm</a> </h2>

Change directory to your local development directory, and run <tt>gmake</tt>. e.g.

<tt> cd $HOME/mycm gmake </tt>

or let <tt>gmake</tt> change directory for you. e.g.

<tt> gmake -C $HOME/mycm </tt>

A <tt>generated</tt> directory will be created for the object files, dependency files, and preprocessed fortran files, and a <tt>dso</tt> 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 <tt>source</tt> are taken from the global CMISS directory as indicated by the <tt>CMISS_ROOT</tt> environment variable.

If you want an executable without any DSOs then supply the option <tt>STATIC=</tt> to the <tt>gmake</tt> command. The executable will be created in a <tt>bin</tt> directory and may have a different name to the dynamic version.

Run

<tt> gmake help </tt>

for information on making different versions of cm.

<h2><a name="SECTION00052000000000000000"> Running a local cm</a> </h2>

Run the local cm executable by typing the path to the executable. e.g.

<tt>$HOME/mycm/dso/mips3-n32-debug/cm</tt> arguments

You may like to set up aliases for these commands in your <tt>.(t)cshrc</tt> file. (See <tt>man csh</tt> or <tt>man alias</tt>.)

<h1><a name="SECTION00060000000000000000"> Debugging</a> </h1>

Debug the local cm executable with a command such as

<tt>cvd $HOME/mycm/dso/mips3-n32-debug/cm &</tt>

Help on this is available through the irix command <tt>insight</tt> in the book ProDev WorkShop: Debugger User's Guide.

<h1><a name="SECTION00070000000000000000"> Global cm</a> </h1>

<h2><a name="SECTION00071000000000000000"> Compling and linking a global cm</a> </h2>

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 <tt>su</tt>) 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

<tt> cd $CMISS_ROOT/cm gmake </tt>

or

<tt> gmake -C $CMISS_ROOT/mycm </tt>

The alias cmmake is set up in <tt>cmiss_programmer.sh</tt> to change to the appropriate directory for you. So you can just

<tt> cmmake </tt>

On <tt>hpc*</tt>, 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

<tt> cmmake help </tt>

<h2><a name="SECTION00072000000000000000"> Running a global cm</a> </h2>

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.

<tt>$CMISS_ROOT/cm/bin/mips3-n32/cm-debug</tt> 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 <tt>$CMISS_ROOT/bin</tt> are links to these nightly-made executables. If <tt>$CMISS_ROOT/bin</tt> is in your <tt>PATH</tt> 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 <tt>$CMISS_ROOT/cmiss_utils/scripts/cmiss_programmer.sh</tt> 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

<h1><a name="SECTION00080000000000000000"> Dynamic Shared Objects</a> </h1>

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.

<h2><a name="SECTION00081000000000000000"> Dynamic Linking Basics</a> </h2>

Before doing any linking, a copy of <tt>/usr/lib32/so_locations</tt> 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.

<h4><a name="SECTION00081010000000000000"> Stage 1: Producing the DSOs</a> </h4>

This is done with a command like

<tt>ld -shared -n32 -mips3 -update_registry

${DSO_DIR}/so_locations <object-list> -o <dso-name> </tt>

<tt>-shared</tt> indicates that the output is a shareable object.

<tt><object-list></tt> 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 <tt>$startaddress</tt> value.

I don't think it's worth trying to include any statically linked libraries at this stage.

<h4><a name="SECTION00081020000000000000"> Stage 2: Producing the Executable</a> </h4>

Objects, DSOs, and static libraries are linked using something like

<tt>f77 -n32 -mips3 -ignore_unresolved -rpath ${DSO_DIR}

<object/DSO-list> <library-specifiers> -o <executable-name></tt>

<tt>-ignore_unresolved</tt> may be unnecessary

<tt>-rpath ${DSO_DIR} is to let the run-time linker know where to

look for the DSOs.</tt>

<tt><object/DSO-list></tt> 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).

<tt><library-specifiers></tt> 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: <ul><li>Guide to debugging using CVD with CMISS - quick fixes to trap common

errors.

</li></ul>

Personal tools

Editing cm source