History for Editing cm source
changed:
-
<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>
<!--End of Table of Contents-->
<p>
</p><h1><a name="SECTION00020000000000000000">
Introduction</a>
</h1>
<p>
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.
</p><p>
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.
</p><p>
</p><h2><a name="SECTION00021000000000000000">
Local and global versions of cm</a>
</h2>
<p>
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.
</p><p>
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.
</p><p>
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.
</p><p>
</p><h1><a name="SECTION00030000000000000000">
Editing CMISS source</a>
</h1>
<p>
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>.
</p><p>
</p><h1><a name="SECTION00040000000000000000">
Initial Setup</a>
</h1>
<p>
To set yourself up to develop CMISS under Unix, there are a few of steps to
take.
</p><p>
</p><h2><a name="SECTION00041000000000000000">
Environment variables</a>
</h2>
<p>
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.
</p><p>
ie <tt>emacs $HOME/.cshrc</tt>
</p><p>
Set the root path for cmiss and the location of the CVS repository by adding
</p><p>
<tt>
setenv CMISS_ROOT /hpc/cmiss
<br>
</tt>
</p><p>
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.
</p>
<h2><a name="SECTION00041500000000000000">
Setup for CVS</a>
</h2>
<p>
Read [Setting Up for CMISS CVS Access] and follow the instructions there.
</p>
<h2><a name="SECTION00042000000000000000">
Local cm directory structure</a>
</h2>
<p>
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.
</p><p>
<tt>
cvs checkout cm/Makefile cm/make cm/source/fe11.f cm/source/fe20.f
</tt>
</p><p>
or
</p><p>
<tt>
cvs checkout -d mycm cm/Makefile
<br>
cd mycm
<br>
cvs checkout -d source cm/source/fe11.f
<br>
cd source
<br>
cvs update fe20.f
</tt>
</p><p>
</p><h1><a name="SECTION00050000000000000000">
Local cm</a>
</h1>
<p>
</p><h2><a name="SECTION00051000000000000000">
Compiling and linking a local cm</a>
</h2>
<p>
Change directory to your local development directory, and run
<tt>gmake</tt>. e.g.
</p><p>
<tt>
cd $HOME/mycm
<br>
gmake
</tt>
</p><p>
or let <tt>gmake</tt> change directory for you. e.g.
</p><p>
<tt>
gmake -C $HOME/mycm
</tt>
</p><p>
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.
</p><p>
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.
</p><p>
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.
</p><p>
Run
</p><p>
<tt>
gmake help
</tt>
</p><p>
for information on making different versions of cm.
</p><p>
</p><h2><a name="SECTION00052000000000000000">
Running a local cm</a>
</h2>
<p>
Run the local cm executable by typing the path to the executable. e.g.
</p><p>
<tt>$HOME/mycm/dso/mips3-n32-debug/cm</tt> arguments
</p><p>
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>.)
</p><p>
</p><h1><a name="SECTION00060000000000000000">
Debugging</a>
</h1>
<p>
Debug the local cm executable with a command such as
</p><p>
<tt>cvd $HOME/mycm/dso/mips3-n32-debug/cm &</tt>
</p><p>
Help on this is available through the irix command <tt>insight</tt> in the book
<i>ProDev WorkShop: Debugger User's Guide</i>.
</p><p>
</p><h1><a name="SECTION00070000000000000000">
Global cm</a>
</h1>
<p>
</p><h2><a name="SECTION00071000000000000000">
Compling and linking a global cm</a>
</h2>
<p>
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.
</p><p>
Compiling a global cm is the same as compiling a local version.
Either
</p><p>
<tt>
cd $CMISS_ROOT/cm
<br>
gmake
</tt>
</p><p>
or
</p><p>
<tt>
gmake -C $CMISS_ROOT/mycm
</tt>
</p><p>
The alias cmmake is set up in <tt>cmiss_programmer.sh</tt> to change to the
appropriate directory for you. So you can just
</p><p>
<tt>
cmmake
</tt>
</p><p>
On <tt>hpc*</tt>, this alias will also ensure that the source is the latest version in
the CVS repository before running the Makefile.
</p><p>
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.
</p><p>
Further help on compiling other versions and usage of the Makefile can be
obtained using
</p><p>
<tt>
cmmake help
</tt>
</p><p>
</p><h2><a name="SECTION00072000000000000000">
Running a global cm</a>
</h2>
<p>
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.
</p><p>
<tt>$CMISS_ROOT/cm/bin/mips3-n32/cm-debug</tt> arguments
</p><p>
or supply the path to the executable as an argument to cvd to debug the
executable.
</p><p>
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.
</p><p>
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).
</p><p>
If you have sourced
<tt>$CMISS_ROOT/cmiss_utils/scripts/cmiss_programmer.sh</tt> then the
following aliases may be available:
</p><p>
cm - runs the 32 bit version of CMISS
<br>
cmd - runs the 32 bit debug version of CMISS
<br>
cm_mp - runs the 32 bit multiprocessing version of CMISS
<br>
cm_mpd runs the 32 bit multiprocessing debug version of CMISS
<br>
cmo - runs the 32 bit optimised version of CMISS
<br>
cmod - runs the 32 bit optimised debug version of CMISS
<br>
cmo_mp - runs the 32 bit optimised multiprocesing version of CMISS
<br>
cmo_mpd - runs the 32 bit optimised multiprocesing debug version of CMISS
</p><p>
cm64 - runs the 64 bit version of CMISS
<br>
cmd64 - runs the 64 bit debug version of CMISS
<br>
cm64_mp - runs the 64 bit multiprocessing version of CMISS
<br>
cm64_mpd - runs the 64 bit multiprocessing debug version of CMISS
<br>
cmo64 - runs the 64 bit optimised version of CMISS
<br>
cmod64 - runs the 64 bit optimised debug version of CMISS
<br>
cmo64_mp - runs the 64 bit optimised multiprocesing version of CMISS
<br>
cmo64_mpd - runs the 64 bit optimised multiprocesing debug version of CMISS
</p><p>
</p><h1><a name="SECTION00080000000000000000">
Dynamic Shared Objects</a>
</h1>
<p>
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.
</p><p>
What follows is some possibly outdated information that might enable you to
get DSOs working.
</p><p>
</p><h2><a name="SECTION00081000000000000000">
Dynamic Linking Basics</a>
</h2>
<p>
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.
</p><p>
Compiling is done the same as for with static linking.
</p><p>
Linking is done in two stages.
</p><p>
</p><h4><a name="SECTION00081010000000000000">
Stage 1: Producing the DSOs</a>
</h4>
<p>
This is done with a command like
</p><p>
<tt>ld -shared -n32 -mips3 -update_registry
${DSO_DIR}/so_locations <object-list> -o <dso-name> </tt>
</p><p>
<tt>-shared</tt> indicates that the output is a shareable object.
</p><p>
<tt><object-list></tt> can be one or many modules.
</p><p>
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.
</p><p>
I don't think it's worth trying to include any statically linked
libraries at this stage.
</p><p>
</p><h4><a name="SECTION00081020000000000000">
Stage 2: Producing the Executable</a>
</h4>
<p>
Objects, DSOs, and static libraries
are linked using something like
</p><p>
<tt>f77 -n32 -mips3 -ignore_unresolved -rpath ${DSO_DIR}
<object/DSO-list> <library-specifiers> -o <executable-name></tt>
</p><p>
<tt>-ignore_unresolved</tt> may be unnecessary
</p><p>
<tt>-rpath ${DSO_DIR} is to let the run-time linker know where to
look for the DSOs.</tt>
</p><p>
<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).
</p><p>
<tt><library-specifiers></tt> are for static libraries.
</p><p>
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.
</p><p>
Some extra things that should be in this document:
</p><ul><li>Guide to debugging using CVD with CMISS - quick fixes to trap common
errors.
</li></ul>
Forgot your password?
New user?