Software Development at CFHT

Anyone contributing software to the main development tree (/cfht/src/..., formerly /usr/local/cfht/dev/{pegasus,medusa,etc.}) must 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.

Changes

2000-4-20: Updating for today's discussion.  
1998-12-14: This version is still here.
1996-11-11: Created.

Contents

Location of Files
Makefile conventions
Index files
Changes files
Check-in and Check-out
Releases
Archival Back-ups

Location of Files (Back to contents)

All CFHT Unix machines now have a /cfht/ automount point. Subdirectories are as follows:

/cfht/src/

This directory is always a mount of saturn:/usr/local/cfht/dev/, 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 new Makefile setup will build stuff from /cfht/src/ even if your true working directory is somewhere in /usr/local/cfht/dev/.

/cfht/man/

This is always a mount of saturn:/usr/local/cfht/man/.

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. Most Solaris 2.6 binaries need to be built on makani right now. Other than that, new versions need to be built on every machine that uses them. You can look at /etc/auto.cfht on a particular machine to be sure.

/cfht/bin/

The file /cfht/src/local-install.sh 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 local-install.sh 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/local-install.sh script and re-run it.

/cfht/lib/

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.)

/cfht/include/

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.

/cfht/conf/

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

/cfht/obs/

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 documentation. (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.)

Makefile conventions (Back to contents)

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:

1. A project Makefile which doesn't install anything but just lists the subdirectories that "make world" should traverse. It is not enough to simply give the subdirectories in the order that they should be compiled! You must set up proper dependencies using the form in the example below, or "make -j" for multi-processor machines will not work properly. Here is an example:

   ---

   # Makefile for cli-2.8 project tree
   include ../Make.Common
   SUBDIRS=libcli director directest clicmd clicap clidup runon
   clicmd.d clicap.d clidup.d runon.d director.d directest.d: libcli.d.install
   include ../Make.Common
   

   ---

   The dependency line indicates that libcli must be installed before the others can even be built.

2. A Makefile for a C program. Programs should always be at the "leaves" of the directory tree, meaning there should be no more subdirectories for "make" if at this level. Example:

   ---

   # Makefile for directest
   include ../Make.Common
   $(EXECNAME) $(EXECNAME)-pure: $(OBJS) -lcli -lcfht
   include ../Make.Common
   # Rest of Makefile is auto-generated
   

   ---

3. A Makefile for a C library. These are even simpler, assuming you just want every *.h file installed and every *.c file compiled:

   ---

   # Makefile for libcli.a
   include ../Make.Common
   include ../Make.Common
   # Rest of Makefile is auto-generated
   

   ---

   If you need to explicitly list your source files, that is possible too. See the link below.

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 on the Make.Common page.

Index files (Back to contents)

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
  email			daprog@cfht.hawaii.edu

# Contents:

  Makefile		Use with GNU make to build director

  director.cc		main event loop for director program

  builtins.cc		builtin commands that director handles itself

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

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

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

  setserial.h		Stty type-stuff used by Pipes.cc 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.

Changes files (Back to contents)

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".

VERSION=2.7

---

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.

RCS Check-in and Check-out (Back to contents)

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.

Initial Check-in

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

• Things are functioning and you may want to return to this version later if things break.
• Somebody else may need to edit your file soon.
• You fear that someone else may edit the file by accident (if you don't check it in, our default umasks allow anyone else in the group to accidentally edit your files. Once entered into the RCS system, this can no longer happen.)
• The file is at a stage where it is actually being used by engineering staff or observers. (--> If the file/project has reached this stage, you must have checked it in to RCS by now. The only exception to this will be if you are truly the only maintainer and you wish to make an archival backup of the entire project tree instead. You could do both. But if you only make the archive, give it a version number or date that matches the binaries and leave it in the source tree where others can find it.)

First, make sure an RCS subdirectory exists or RCS will make a mess in the current directory. If it doesn't exist, simply run:

    % mkdir ./RCS

Initial check-in for foo.x will then look something like this, assuming you set up the alias properly:

    % ci foo.x
    RCS/foo.x,v  <--  foo.x
    enter description, terminated with single '.' or end of file:
    NOTE: This is NOT the log message!
    >> This is my description for file foo.x
    >> .[Return]
    initial revision: 1.1
    done
    % _

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.

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)
    done
    % _

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.)

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
    done
    % _

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]
    done
    % _

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.

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
    branch:
    locks: strict
    access list:
    symbolic names:
    keyword substitution: kv
    total revisions: 2;     selected revisions: 2
    description:
    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>
    
    RCSID("$Id");
    
    /* ...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 */

RCS and Emacs

If you use Emacs or XEmacs, you should be able to use the key-strokes ^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.

Summary of Check-in/Check-out

• Don't use branching version numbers.
• Don't check in files without -u or they'll "disappear".
• Use $Id$ inside a comment somewhere if possible. (Please convert old $Header$'s to $Id$'s.)
• Use $Log$ if appropriate (otherwise: rlog will always work)
• The commands you need to know are:
  • co foo.x (assuming co is aliased)
  • ci foo.x (assuming ci is aliased)
  • rlog foo.x
  • rcsdiff -c foo.x
• Never circumvent RCS to "save time"!