The most common way of using coda is to create a configuration file in your home directory. On UNIX systems, the file is named $HOME/.codarc while on VMS machines it is named SYS$LOGIN:CODA.DAT. On either system, to use a different file, set the environment variable CODA to the name of the file. This is useful to share a common a file among project members. The config file identifies where the server host is, your name (and password) on the server, and where the Codafile and sources are to be found.
The config file is a set of lines that make name-value pairs. Lines starting with a pound sign are ignored. The following is a sample configuration file; the field names are explained below:
## Server host and port number host papaya.bbn.com port 1999 ## Our name and password on the server host user rsalz pass doubtful ## Directory to start from, name of the file to read dir /usr/cronus file src/make_all/Codafile ## #root /nfs/papaya/u1/cronusbuild/cronus slow n verbose 1 ## Can client have newer files? Yes, while porting to it younger y
In addition to using the config file, it is possible to specify the parameters by using command line flags. Any values set by flags override the values in the config file. The following tables matches names in the config file to command line flags.
File Flag Meaning
host -h Name of the server host port -p Port to connect to; default is 1999 user -u Your login name on the server pass -p Your password on the server; see below dir -d Directory for server to change to file -f File to read (if not Codafile) in the directory given above -n No action, just report what would be changed root -r Path to find files in; overrides what the Codafile declared slow -s Do byte-for-byte comparisons -t Trace the protocol verbose -v How much information to show younger -y Allow newer files to be on the client owner -o Retain original ownership
If your password is not listed in the config file, or specified on the command line, coda will ask you for it. If you do put your password in the config file, make sure that nobody else can read the file!
Once the file has been read, the server will send over a list of files and directories. Coda will parse this list, and update any files and directories it has to.
For efficiency, coda normally just checks the sizes of the local and master copy, and will only update the local copy if they are different. If the modification dates are different, coda will get a copy of the file and do a byte-for-byte comparison to see if the files actually are different. If the ``-s'' flag is used, coda will ignore the time check, and will get every file and compare it with the local copy.
If you use the ``-n'' flag, coda will not do work, but will instead just report what files and directories are out of date.
During a port, a client will often have files that have been modified after they have been obtained from the server, but before the changes have been integrated into the master sources. On systems where the client's timestamp can be trusted (e.g., not on VMS because there is no equivalent of the utime(2) call), the ``-y'' flag may be used to specify that the client might have files that are younger, or more recent, than those on the server. The default option, ``-yn'' will cause coda to check if the files are different, and overwrite them, if the timestamps are different in any way.
By default the person who runs coda will be the owner of the files. To make the ownerships match those on the server, use the ``-oy'' flag. This is probably more correct in a production environment than when porting.
If you use the ``-v'' flag, coda will give more verbose information about what it is doing. For example, ``-v1'' will list all files and directories that have to be created. If you use the ``-v2'' flag, coda will report when it has to change the ownership or permission on files, such as when a file has the right time and size, but is owned by the wrong person. Since it is normally not a big problem if the wrong person owns a file, or if it has the wrong permissions, coda does not complain if something cannot be fixed. You can use the ``-v3'' flag to see a message whenever the program cannot set the file mode or ownership. If you use the ``-v4'' flag coda will report on every file as it does the byte-for-byte comparison of slow mode. You should probably always use either ``-v1'' or ``-v3.''
To trace all interactions with the server, use the ``-t'' flag; this will provide output like the following:
prompt% coda -d/usr/rsalz -f coda/Codafile -h papaya -u rsalz -x ... -t misc
<<<ACK-Hello FIG.BBN.COM; how are you today?
>>>USER rsalz ...
<<<ACK-Logged in rsalz
>>>GOTO /usr/rsalz
<<<ACK-Done
>>>READ coda/Codafile
<<<ACK-Done
Doing misc...
>>>LIST misc
<<<DAT ITEM W=d N=cbin U=-2 G=121 M=511 S=512 T=609796129
<<<DAT ITEM W=f N=cbin/dcc U=-2 G=121 M=493 S=150 T=603474106
...
<<<ACK-Found 105 files
Found 105 files
mkdir cbin
Update cbin/dcc
...
>>>QUIT
prompt%
The ``-c'' flag prints out copyright and version information.
Blank lines are ignored, as is anything after a pound sign. Whitespace is not significant. There are a few keywords, and they appear in bold in the examples below. To use a keyword as a filename (e.g., if you have a directory named class), put it in quotes. It is also necessary to quote words if they contain any characters other than letters, numbers, or the characters period, slash, or underscore.
There are four constructs in a Codafile: parameter definitions, host definitions, class definitions, and file definitions or blocks. They may appear in any order.
Parameter definitions are a catch-all for miscellaneous parameters. There are currently three parameters. Most pathnames in a Codafile will be relative paths, the ``root'' is used for any directories or files that do not start with a slash. For example:
At times it is useful to use the same Codafile for several different source trees. The easiest way to do this is to not allow the clients to specify the different roots. Since this can be a security hole, a Codafile can specify that the root directory specified in the file may not be overridden by the client. To do this, use the following line:
The final parameter controls whether or not binary files are sent. When preparing a list of files, the server can read the first few bytes to see if a file is an ``a.out'' file, and if so, it will not list it. To suppress this check, add a line like this:
Host definitions are used to name the hosts that are allowed to receive the distribution, and to identify the system type. Both the names and types are arbitrary text strings; host names are converted to all uppercase. A client's hostname must be defined in the Codafile before the server will send any files to it.
host citron.bbn.com = VMS ; host pineapple.bbn.com = ultrix ; host doe.bbn.com = sun4 ; host papaya.bbn.com = sun3 ;
In order to make the Codafile shorter, hosts are grouped into classes. For example, it is convenient to be able to say ``give all the Unix machines the files in foo.'' Classes are defined in two ways, by being named as a system type in a host definition, like above, or by appearing in a class definition, like this:
class SUN = sun3, sun4 ; class UNIX = SUN, ultrix ;
define root = /usr/spool/ftp ; define binaries = no ; host _ANYHOST = guest ; class WORLD = _ALL, _ANYHOST ;
The most important part of a Codafile is the file definitions, or blocks. These have the following syntax (optional items are shown in square brackets):
[ only_explicitly ] name : class {
item
[ except [directory] class pattern, ... ; ]
[ except [directory] class pattern, ... ; ]
item
...
directory item
[ except [directory] class pattern, ... ; ]
}
Within the block, each item names either a file or a directory. If the item does not start with a slash, then the root is prepended. If the item is a directory, than the server will walk down all the files and directories beneath the named item. To name just a directory, put the word directory before the item name. For example:
headers : _ALL {
include
directory cetc
cetc/hostfile
cetc/typefile
/etc/motd
}
Items can be given exception lists. Exception lists are patterns similar to shell wildcards:
Character Meaning
? Any single character
* Zero or more characters
[abc..09] Any single character inside the brackets
The sequence ``a-z'' can be used to mean ``abcdefghijklmnopqrstuvwxyz''
[^a-z] Any single character not inside the brackets.
\x The character ``x'' has no special meaning (e.g., \?)
For example, with the following hierarchy:
clib/commandfile clib/cronus.a clib/diamond/fonts/helvetica10.font clib/diamond/fonts/tv8b.font clib/diamond/lib.a clib/diamond/config clib/editkeysfile clib/lint/llib-lasync clib/lint/llib-lasync.ln clib/lint/llib-lulib clib/lint/llib-lulib.ln clib/malloctool.a
library : _ALL {
clib
except _ALL "*.a", "*.ln" ;
except directory VMS diamond, lint ;
}
With a good set of classes it is quite easy to tersely specify distributions. The following example suffices to distribute the major part of the Cronus source tree:
sources : _ALL {
src
exceptVMSMakefile, "*.sh", "*.s", "llib-l*" ;
exceptUNIXdescrip.mms, "*.opt", "*.com", "*.mar" ;
except_ALL"*.[oa]", "*.ln" ;
except_ALLa.out, core, foo, tags ;
}
Copyright 1989 BBN Systems and Technologies Corporation. All Rights Reserved. This is free software, and may be distributed under the terms of the GNU Public License; see the file COPYING for more details. $Header: coda.1,v 2.0 90/03/23 15:01:50 rsalz Exp $