next up previous contents
Next: 12. The Observing Up: CFHT Data Acquisition Previous: 10. Development Tools   Contents


11. Software Organization, Versions, and Conventions

Anyone contributing software to the main development tree /cfht/src/..., should follow these basic guidelines. You may be able to keep track of what you are doing without following all of this, but in order for everyone in the group to be able to make some basic assumptions about the software in /cfht/src/, we all need to comply. If you don't, you could be causing one of your colleagues (and possibly yourself) a huge headache some time in the future. This is an attempt at a practical guide on how to maintain some basic organization in the CFHT source directories. This organization also provides some security for software used in critical functions of observing. Even if your software is not in this category, it has a better chance of being maintained if we follow some consistent methods.

11.1 Location of Files

All CFHT Unix machines now have a /cfht/ automount point. Subdirectories are as follows:
This directory is always a mount of mohala:/local/cfht/src/, which contains subdirectories "pegasus" for global session-related software, "medusa" for instrument or sub-system specific software, and "epeus" for third party software used in observing sessions. The Makefile setup will build stuff from /cfht/src/ even if your true working directory is somewhere in /usr/local/cfht/dev/.

Some of our programs actually have man pages (documentation.)

The rest of the directories ( bin, lib, include, and obs) are different for different machines. Almost all machines at the summit, including the Sparc Engines now have their own, local copies of these directories. You can look at ypcat -k auto.cfht to be sure.

The file /cfht/src/ makes a set of symbolic links into /usr/local/bin of every machine at CFHT, pointing to a few programs in /cfht/bin/ that are generally useful. For example, the "clone" command for director can be run by any user from any machine (as long as they at least have /usr/local/bin/ in their PATH). unroll and tcshandler (Oops... this causes it to look for tcshandler.par) are a couple of other links created by at the moment. /cfht/bin/ shouldn't need to appear in anyone's PATH (if it does, it should be at the end.) Observing accounts have symbolic links in $HOME/bin and if you wish to make programs runnable by staff members, add them to the /cfht/src/ script and re-run it.

At the present time, we only use static libraries, so at runtime, nothing uses /cfht/lib/. On saturn or in Waimea, /cfht/lib/ generally contains the latest static libraries matching what we are working on in the source tree, so if you build and link on saturn, that is what your executable will get. At the summit, we only do "make install"s of libraries when they have been tested, so the stuff in /cfht/lib/ on neptune may differ. This means that if you build executables at the summit, they can behave differently that those built from the same sources in Waimea. Copying a binary built on saturn into an account will not be subject to this, but that could change if we ever start using sharable libraries in /cfht/lib/. (In that case, your executable would load whatever is in /cfht/lib/ at runtime, so an executable could change its behavior simply by being moved to the summit.)

This directory must always be paired with a matching /cfht/lib/. It contains include files that are installed at the same time as the matching library in /cfht/lib/. With or without sharable libraries, it will never get used at runtime, though.

This contains installed par-files and other text files that can get used by programs at runtime.

This is the last of the architecture-specific directories. It contains intermediate object files (.o) and executables and libraries before they are installed. "make clean" removes entire subdirectories from this tree to force recompilation, but normally the files in /cfht/obs/ are used by "make" to resolve dependencies and allow it to figure out which components have changed and need to be rebuilt and/or reinstalled.

There is another use for the files in /cfht/obs/. When programs are installed in /cfht/bin/, they are stripped of debugging symbols. As long as the last step you did was a "make install", there will be a matching copy with symbols in /cfht/obs/progname/progname which can be used by gdb to debug cores or running versions of the installed copy in /cfht/bin/. There is more information on how to do this the Makefile section of this document. ( Note that as soon as you change the source and do another "make" without a "make install" the version in /cfht/obs/ will no longer match, and gdb will warn you of this if it happens.)

11.2 Makefile conventions

Within "pegasus", "medusa", and "epeus" each project or instrument may contain a subdirectory. When possible, creating a separate subdirectory for each program is recommended because it keeps the Makefiles simple. I currently do not have an example of how to generate more than one compiled executable from a single subdirectory. If you make one, please put it here as an example. Most Makefiles include "Make.Common" twice. So far I only have three examples:

How does the Makefile know whether it has to generate a library (.a) or an executable? The name of the subdirectory always gives the name of the object being generated, and if it starts with "lib*", the Makefile knows it has to make a library. This means you must create a subdirectory for each library and program, and they must have the same name. More specifics on Makefiles are given in the Make.Common section.

11.3 Index files

Placing some kind of README or file-list at each directory node is generally a good idea. If you use the suggested format below, you will able to take advantage of the "make titles" function of Make.Common, which automatically inserts a description and copyright comment into the top of several types of source files. Here is the suggested format. The file must be called Index if you want "make titles" to find it:

# Description:

  package		DIRECTOR cli wrapper
  version		2.8
  organization		Canada-France-Hawaii Telescope

# Contents:

  Makefile		Use with GNU make to build director		main event loop for director program		builtin commands that director handles itself

  Curs.hh		manages screen output and keyboard input		See Curs.hh

  Roll.hh		holds of the latest N lines echoed in shared memory		See Roll.hh

  Pipes.hh		reads line-by-line from pipe or fifo sources		See Pipes.hh

  setserial.h		Stty type-stuff used by to set up serial ports
  setserial.c		See setserial.h

To see how "make titles" inserts this information in C code, see the files in /cfht/src/pegasus/cli/director2/ for an example. "make titles" will also search the files listed in Index for unusually long lines and markers that you can leave within comments. If it finds === (three equal signs) it will be flagged as a warning (parsable by the emacs compile buffer, so you can click with the middle mouse button in the editor and it will automatically pull up the file with the cursor in the correct place) and %%% (three percent signs) will be flagged as an error. Files that exist but are not identified in Index are also flagged. You can run the command "titler" with no arguments to get some built-in help on this utility.

11.4 Changes files

Changes files may still serve some purpose, but in general they can probably go away when we start using SVN for everything. You can create a branch in SVN and label it accordingly, or for snapshots along the way that don't need to be branches, SVN also supports tagging releases.

Placing a file called "Changes" in a subdirectory can serve several purposes. RCS (see below) keeps a change log on a file-by-file basis. If it useful to describe a change in terms of what it did to the over-all project, it might help to maintain a Changes file that tracks this development.

Second, if you make all of the lines in Changes into comments, except for the last line, which sets a version number, then you can include Changes in your Makefiles and use it to assign a "1.0, 1.1, 1.2, 2.0 ..." style versioning to your program, rather than the Pegasus default (the date, in a string *-YYMMDD). In this case, it is usually most meaningful to have a Changes file only for the top-level of a project, and then include it in the Makefiles of all the components, so that a set of utilities all have a consistent version number. Using these manual version numbers gives you a little more flexibility, but you must use it responsibly. For example, once version "2.5" is being used, especially in an observing environment, you had better switch to version "2.6" as soon as you start modifying the code again to avoid confusion, no matter how small the changes might be. On the other hand, with the default dated versioning, you do not have the option to move to a new version number until the next day! Here's an example of the Changes from the cli (director) project:

# CLI Version History
# 1.0 - First version.  Used for uh8k run in 97I.
# 2.0 - Shared memory roll buffer. status: changed to statusbar: message
# ------CHANGE IN SHARED MEMORY SEGMENT SIZE (2.0/2.1 can't clone each other).
# 2.1 - More efficient packing of roll messages (Shm size from 1M->160K)
# 2.2 - Silently handle SIGALRM for client "low priority". Used for aobir 97II.
# 2.3 - Allow spaces in comlist for displaying in help. Used for uh8k 97II.
# ------CHANGE IN SHARED MEMORY SEGMENT SIZE; Versions above/below this
# ------line cannot attach to each other's shared memory segments!
# ------Use of <2.4 should be discontinued anyway, as 2.4 is stable and
# ------fully supports all features of previous 2.x version.  Extra entries
# ------have been added to shared memory structures to hopefully avoid the
# ------need for further incompatibilities.
# 2.4 - More tolerant of named pipe problems; blank entries in shm for future
# 2.5 - Better debug info for director and clicmd; re-start write()'s to pipes.
# 2.6 - Minor fixes to curses screen update code; detect rmd() errors.
#       Entire environment is now passed to agents on remote hosts.
#       Clicmd utility now supports sym-linking to command names.
#       Clones can only be activated by entering account password first.
#       Clones automatically get infosize of parent if no '-i' option given.
#       Infolines that run to end of screen don't erase next line anymore.
#       Autoprobe for rxvt turns on color support even if TERM variable wrong.
#       Added -t TERM and -C (no title clock) command line options.
#       cli_system() no longer interruptable by SIGALRM or other signals.
#       cli_sh_cmdstr() and cli_remsh() added to libcli.a
#       Now requires Posix "termios.h" terminal i/o routines.
# 2.7 - Removed cli_sh_cmdstr and cli_remsh().  Replaced with external "runon".

And it is included in the Makefiles below as follows:

include ../Make.Common
include ../Changes
include ../Make.Common

So that installed binaries will be versioned as foo-2.7 rather than foo-981209.

11.5 RCS Check-in and Check-out

We'll move /cfht/src/ completely under the management of an SVN repository! The following information will be kept here just a short while longer because it still/also applies to DNS zone files, automount maps, and other system things which are also on the path to be changed soon.

Once a group of files has reached a stable, usable condition, each file should be "checked in" to RCS. After this has been done, you should NEVER move, use root access to change anything, or manually chmod/chown a file, or otherwise try to circumvent RCS! Learn these simple commands and save all of us a lot of confusion in the long run.

You may find it useful to create the following aliases (the commands " co" and " ci" are already aliased in this way if you use bash at CFHT.) The examples below assume you have them. If not, be sure to add the options each time you type the command. Note that you can call the alias something other than co and ci if you don't want to clobber the original command.

ci " ci -V3 -u"
co " co -V3 -l"

The -V3 means operate in a mode compatible with RCS version 3. (I'm not sure this is needed by new projects anymore, but it just makes things compatible with the co/ci that are still in /usr/bin/ on our HP-UX 9 machines.) The -u/-l mean that you will always be unlocking a file when you check it in, and locking it when you check it out. Locking just means no one else will be able to edit the file while you're working on it.

11.5.1 Initial Check-in

Lets say you've reached a stage with file foo.x that meets one of the following:

11.5.2 Help, the file is now gone!

Well, it shouldn't have disappeared, but if you didn't alias ci to be " ci -u" then RCS will remove the file from the current directory. To keep things simple, we never want to use RCS in this way, so if this happens, please fix your aliases and then check the file out again immediately. But don't worry, RCS will never remove the ,v version of the file that lives in the RCS subdirectory.

11.5.3 Check-out

The next thing you'll probably want to do is check the file out immediately again, to continue editing what will become version 1.2 upon the next check-in:

    % co foo.x
    RCS/foo.x,v  -->  foo.x
    revision 1.1 (locked)
    % _
The " (locked)" is important, and shows that you have exclusive control over editing the file now. In case someone else already grabbed the lock before you, a message like this may show up:

    % co foo.x
    RCS/foo.x,v  -->  foo.x
    co: RCS/foo.x,v: Revision 1.1 is already locked by bonehead.
    % _
If you see this, try to contact bonehead and get them to check the file back in, using the procedure below. Another thing you might see is this:

    % co foo.x
    RCS/foo.x,v  -->  foo.x
    revision 1.1 (locked)
    writable foo.x exists; remove it? [ny](n):
    % _
Say ` n'! This appears if you already have the file checked out. If you check it out again, you will get back to the old version. The only time you would want to do this is if you want to cancel all of your edits since the last check-in. In this case, I strongly recommend you first run rcsdiff on the file to see what changes you are about to lose in reverting to the previous version. (See the rcsdiff example below.)

11.5.4 Check-in

If you haven't made any changes, but you want to unlock the file again so someone else can check it out, just run ci and it will be smart enough to figure out that there's no need to make a "version 1.2" and it will just return the file to its safe, checked-in state:

    % ci foo.x
    RCS/foo.x,v  <--  foo.x
    file is unchanged; reverting to previous revision 1.1
    % _
On the other hand, if you've made changes to the file, I strongly recommend running " rcsdiff -c" on the file first to double-check that you've only changed the parts of the file you meant to change. rcsdiff will show you what's different between the last checked-in version and the version you are about to check in. The -c option selects "context-style" output, which is shown below:

    % rcsdiff -c foo.x | less
    RCS file: RCS/foo.x,v
    retrieving revision 1.1
    diff -c -r1.1 foo.x
    *** /tmp/T0a19438       Wed Dec  2 23:29:38 1998
    --- foo.x       Wed Dec  2 23:27:55 1998
    *** 1 ****
    --- 1,2 ----
      This is a dummy file, dummy.
    + Here's a new line I added to the end for version 1.2.
    % _
New lines are marked with a "+", removed ones with a "-" and changed ones will show up twice, marked with "!" (first the old one, then the new one.) If this all looks good, then check in the file, and summarize the changes shown by rcsdiff by typing in a line or two describing what's new.

    % ci foo.x
    RCS/foo.x,v  <--  foo.x
    new revision: 1.2; previous revision: 1.1
    enter log message, terminated with single '.' or end of file:
    >> Added a line to the file for demo purposes
    >> .[Return]
    % _

If you ever receive anything different than what you see in the examples here, PLEASE do not try to force things to work. Get help and clean up the mess immediately, before things get out of hand.

One final note on check-in: To keep things simple, I recommend avoiding branching feature of RCS versioning.

11.5.5 Rlog and RCS keywords

You should insert a $Log$ token in a comment near the top of your file, so RCS will maintain a log message history below it. This can quickly lead to files with several pages of log messages and a tiny bit of code at the bottom, so (if you are certain that none of the log messages were manually edited) you can trim this log and place a comment at the bottom showing how to get the full log:

 * $Id: cfp_file.c,v 2.13 1999/08/23 22:09:58 thomas Exp $
 * $Log: cfp_file.c,v $
 * Revision 2.13  1999/08/23 22:09:58  thomas
 * Moved unlink's from DEBUG to DEBUGCPP
 * Revision 2.12  1999/08/05 01:06:28  thomas
 * Fix strcat -> strcpy in one path of interactive copy
 * . . . RCS Log truncated.  Use "rlog" command on this file for complete log.

Assuming everyone faithfully put useful messages in the log at check-in time, you can always access the log information separately using the rlog command:

    % rlog foo.x | less
    RCS file: RCS/foo.x,v
    Working file: foo.x
    head: 1.2
    locks: strict
    access list:
    symbolic names:
    keyword substitution: kv
    total revisions: 2;     selected revisions: 2
    This is my description for file foo.x
    revision 1.2
    date: 1998/12/02 23:32:00;  author: isani;  state: Exp;  lines: +1 -0
    Added a line to the file for demo purposes
    revision 1.1
    date: 1998/12/02 23:17:40;  author: isani;  state: Exp;
    Initial revision
    % _

Verify this first before trimming a log in the source!

Above the $Log$, insert $Id$ on a comment line. RCS will change this key into a useful summary of information about the file, and will automatically keep it current each time you co and ci the file. In C code, you should also use the RCSID(); macro defined in <cfht/cfht.h> so that compiled .o files contain a string indicating from which version of the C file they were generated. In any case, try to include $Id$ in at least some kind of comment near the top of the file so that it is obvious to anyone editing that the file is under RCS. Here's a short C file that shows what $Id$'s look like when you insert them:

     * Copyright, blah blah blah blah
     * $Id$
     * $Log$
     * . . .
    #include <cfht/cfht.h>
    /* ...code starts here */

And here is how they look after RCS has replaced them:

     * Copyright, blah blah blah blah
     * $Id: test.c,v 1.1 98/12/03 17:36:24 isani Locked $
     * . . .
    #include <cfht/cfht.h>
    RCSID("$Id: test.c,v 1.1 98/12/03 17:36:24 isani Locked $");
    /* ...code starts here */

11.5.6 RCS and Emacs

If you use Emacs or XEmacs, you should be able to use the key-strokes Control-X-v-v to lock and unlock a file instead of running co and ci from the command line. This way you probably won't get the -V3 option, but I don't think it is very important except for things like consistent log formatting in older files. -V3 also affects the formatting of the information in a $Header$ keyword. Files that have $Header$ should really have $Id$ instead, and there should be no problem changing them to $Id$'s in which case the -V3 option makes no real difference either way.

11.5.7 Summary of Check-in/Check-out

11.6 Releases

Pegasus only has ways of making an entire release of all the software in the development tree, and making a binary release of everything used by a specific observing account. These are covered in another document. Releases or backups of source trees can be made on a smaller scale using the more manual methods below.

11.7 Archival Back-ups

We will use SVN copies (tags, branches) for this once we have migrated everything over from RCS.

11.7.1 Summary of Archiving/File maintenance commands

ls -latr
Lists all files with the most recent ones at the bottom.
find -newer somefile
Lists files modified after somefile.
cp -av orignal backup
Creates exact backup copies of files or directories.
diff -rc first second
Generates context diff output of files or directories.
make tar
Creates a compressed tar image of a project, excluding RCS. Use this just before upgrade VERSION number.
tar czvf FILE.tgz FILES
Creates compressed tar file. (Use "make tar" on source directories.)
tar dzf FILE.tgz
Lists differences between files on disk and tar file.
tar tzvf FILE.tgz
Lists everything in the tar file.
tar xzvf FILE.tgz
Extracts the files into the current directory, overwriting anything in the way.

next up previous contents
Next: 12. The Observing Up: CFHT Data Acquisition Previous: 10. Development Tools   Contents
Sidik Isani