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.
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.
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.)
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:
# Makefile for cli-2.8 project tree
include ../Make.Common
SUBDIRS=libcli director clicmd clicap clidup runon
clicmd.d clicap.d clidup.d runon.d director.d: libcli.d.install
include ../Make.Common
The dependency line indicates that libcli must be installed before the others can even be built.
# Makefile for directest
include ../Make.Common
$(EXECNAME) $(EXECNAME)-pure: $(OBJS) -lcli -lcfht
include ../Make.Common
# Rest of Makefile is auto-generated
# 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 in the Make.Common section.
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 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". 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.
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.
Lets say you've reached a stage with file foo.x that meets one of the following:
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
% _
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.
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.)
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.
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 */
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.
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.
We will use SVN copies (tags, branches) for this once we have migrated everything over from RCS.