How Church Project Members Share Source Files
Source files for papers and code written by project members are
maintained at Boston College (BC). Here's how to access and update
the shared source repository.
Be aware that some of the specific information in this
document is slightly outdated. If you encounter problems ask one of
the other members of the Church Project
for help.
Quick Start
These directions should help you get started quickly. Follow links to the
endnotes for fuller explanations and alternative approaches.{note
endnotes}
One-time Setup
Get a BC account.
You need an account at BC that is part of group church.
(Contact Bob Muller if necessary.)
In what follows, we'll assume your login name there is
yourname. At BC, put
eval `~church/bin/churchenv`
in your ~/.cshrc or ~/.bashrc file.{note
churchenv script}{note
shell games}
Choose whether to work remotely.
You can either work at BC, on a host that has direct access to
/usr/users1/church (where our shared files are archived),
or you can work on another machine and access the sources remotely.
Working remotely requires a bit more initial setup, but the procedures
after that are the same. We'll call the machine where you do Church
work your work host.
Setup to use CVS.
Church sources are under CVS control. Make sure that you can run the
command cvs -v on your work host.
CVS needs to know how to find the source repository. To tell it, you
specify a repository root. For working locally at BC, this
string (we'll call it your-repository-root) is
/usr/users1/church/cvsroot
If your work host is remote, then
your-repository-root should be
:ext:yourname@cs.bc.edu:/usr/users1/church/cvsroot
instead.{note remote repository} Either
way, set the environment variable CVSROOT on your work host
to contain your-repository-root. For example, put
setenv CVSROOT your-repository-root
in your ~/.cshrc file.{note
CVSROOT}
If working remotely, setup to use ssh.
By default, CVS uses the protocol of the UNIX rsh command
to implement remote access. For security reasons, BC has disabled
rsh access.
ssh is a secure replacement for rsh
that we use instead. To make CVS treat ssh as an alias
for rsh, set environment variable CVS_RSH on
your work host to ssh. For example, put
setenv CVS_RSH ssh
in your ~/.cshrc file.
Skip the rest of this item if you are already able to issue the
command
ssh cs.bc.edu -l yourname
on your work host and have it log you in to BC without challenging
for a password or passphrase. Otherwise, ...
Generate a private/public key pair.
On your work host, run ssh-keygen. It asks you to
make up a passphrase.{note
passphrases} It puts the private key
in ~/.ssh/identity and the associated public key in
~/.ssh/identity.pub.
Copy your public key to BC.
The public key just created is one line (albeit a long one) of
ASCII text. A copy of that line needs to be added to
~/.ssh/authorized_keys at BC. Create the latter file at
BC if necessary. Either ftp file
~/.ssh/identity.pub from your work host to some
temporary spot at BC and append it to
~/.ssh/authorized_keys there, or use cut-and-paste in
editor windows (being careful to not to alter that long line).
{note
file authorized_keys}
Set permissions.
ssh is very picky about ownership and permissions on
the files and directories that concern it. At BC and on your work
host, make sure that your home directory is not writable by anyone
but you. If you have files ~/.rhosts or
~/.shosts at BC, make sure they are owned by you and
are not writable by anyone else. On both hosts, type
chmod -R go-rwx ~/.ssh
Test your ssh setup.
To avoid having to give a password or passphrase on every
transaction that uses ssh, you'll want to have
an authentication agent that is reachable from the environment in
which you do your development.{note
agent activation} At BU and BC, the Perl
script ~church/bin/ssh-agent-setup
simplifies starting and reusing authentication agents. Copy it to
your work host if necessary, and be sure it's in your
$PATH. Then issue
eval `ssh-agent-setup`
In general, this either finds an existing agent of yours and
reuses it, or it starts a new one and prompts you for a passphrase.
(In the latter case, give it the passphrase you made up when using
ssh-keygen.) The reason for the eval above is to
set an environment variable that makes your agent accessible to
commands and subprocesses that you start later from the same shell.
In fact the same agent becomes accessible to the distant processes
that you start via ssh on other hosts! The agent
remembers your identity and authenticates you automatically when a
remote ssh server (such as the one at BC) needs to be sure
who you are. So you should rarely need to type your
passphrase.
To see whether it's working, type
ssh cs.bc.edu -l yourname
(If yourname at BC is the same as your login name on the
work host, you can omit the -l yourname
part.) This should log you in at BC without your having to type
anything further.
Define aliases to ease authentication agent management.
In the preceding step, you started an authentication agent
explicitly. If you work in more than one shell at once, it's a
nuisance to repeat the agent-startup command in each. A
better plan is to define a few aliases in your shell configuration
file. For example, put the following in your ~/.cshrc
file.
alias ssh 'eval `ssh-agent-setup`; \ssh'
alias scp 'eval `ssh-agent-setup`; \scp'
alias slogin 'eval `ssh-agent-setup`; \slogin'
alias cvs 'eval `ssh-agent-setup`; \cvs'
(Remember that ssh-agent-setup must be in your
$PATH.)
Day-to-day Development
Check source files out of the repository.
The sources are organized in trees. Our own code is rooted in a
directory called codefest. Source files of the group's
papers are under papers. Various library materials are
under lib. You can "check out" your own local copies of
these trees or of selected subtrees that interest you. There's no
root directory name in common among these trees, so you might want to
create a ~/church directory for keeping your copies.
Suppose you want to work on the project's paper for PLDI '99. You
learn from those already working away that its repository path is
papers/pldi99, so you cd to your
~/church directory and issue the command
cvs checkout papers/pldi99
This leaves your current working directory with a papers
subdirectory, which in turn contains a pldi99 directory,
and all its contents from the repository. (To be more selective, just
supply a longer path argument.) Now you cd to
papers/pldi99 and begin writing.
Query the status of files checked out.
After working on local sources for a while, you may want to know where
they differ from those currently in the repository, either because of
changes checked in by someone else or because or your own local work.
In the directory of interest, e.g., papers/pldi99, issue
cvs status
This gives a rather verbose report on the status of files in the
current directory and its subdirectories. You can trim the report
down in a couple of ways. You can add file or subdirectory names to
the command line. Or you can filter the output:{note
CVS status}
cvs status |& grep -i status:
This gives a one-line report on each CVS-managed file. Here are the
file-state descriptions you'll see most often:
| Up-to-date |
The file is identical to that in the repository.
|
| Locally Modified |
You have edited the file, and not yet committed your
changes. |
| Needs Patch |
Someone else has committed a new version to the
repository. |
| Needs Merge |
Someone else has committed a new version to the repository, and
you have also made local changes. |
Absorb others' changes to files checked out.
If cvs status shows files that have been changed by
others, you may want to absorb those changes, either to take advantage
of new features or to find out if conflicts exist and resolve them if
they do. To update your local copies, use the command
cvs update
This patches or merges external changes as needed. (Again, use one
or more file or directory arguments to be more selective.) If there
is a textual conflict for some file, say Skeleton.tex, your
version is renamed to something like .#Skeleton.tex.1.2, and
the merged file has chunks that contain both versions of overlapping
modifications:
<<<<<<< Skeleton.tex
\author{J. Wells \and F. Turbak}
=======
\author{J. Wells \and E. Machkasova}
>>>>>>> 1.4
You then replace such chunks with the correct merged text.
Commit changes to the shared repository.
Once you're satisfied that your local changes should be checked in to
the shared source base, use a command like
cvs commit -m "Added section on link-time optimization"
to commit all changes in the current directory.{note
change descriptions} This will balk if
there are conflicts, but that's unlikely if you have just checked
status and found things consistent (or changed them to be so). As
always, use additional names on the command line to commit more
selectively.
This only scratches the surface. Locate a copy of the
CVS manual, preferably one of the online versions that
you can search.
Endnotes
The churchenv script emits environment-setup commands in the
syntax that is appropriate for your shell, whether a C-shell or
Bourne-shell derivative. Among other things, this sets CVSUMASK
to the value 007. That's so that files stored in the CVS repository by
you will be readable and overwritable by members of group church,
but not by others. Note that it does no good to set this variable on your
work host when you are working remotely. It needs to be in your shell
setup at BC.
These notes are biased toward csh and tcsh users.
If you use bash or ksh instead, then you need slightly
different syntax for some of the commands suggested herein.
Both bash and ksh support aliases, but their
alias-definition commands require an equal sign (=):
alias ssh='eval `ssh-agent-setup`; \ssh'
As you know, an equal sign also figures in the setting of environment
variables:
CVS_RSH=ssh; export CVS_RSH
And of course, you put such commands into ~/.bashrc or
~/.profile, rather than in ~/.cshrc.
Remote repository
The repository-root string for remote access encodes the communication
method, the repository host and your account name there, and the absolute
path to the root directory of the repository. The :ext at the
beginning of the string tells CVS to use an external rsh command
(or equivalent, as specified by $CVS_RSH). Otherwise, it uses its
own implementation of the protocol underlying rsh.
CVSROOT
If you use more than one CVS repository and you'd rather not have to keep
changing your CVSROOT variable, you can use the -d
switch to cvs instead. It overrides and current setting of
$CVSROOT. For instance
cvs -d your-repository-root checkout papers/pldi99
(Note that the -d and the root string appear to the left of
the subcommand checkout.) You typically only need the
-d switch when you check sources out of the repository. For
cvs operations you perform in a checked-out directory (like
status, update, and commit), CVS
knows the repository-root string to use.
Passphrases
The passphrases you use with ssh have nothing to do with
passwords of host accounts. Presumably, ssh uses the term
passphrase to stress that fact, and to emphasize that a
passphrase is not restricted to an eight-character limit.
It is possible to omit the passphrase when you generate a private/public
key pair. This would avoid the need to use an authentication agent. But
it's a bad idea, unless your private key is kept on a file system that is
only accessible to you (e.g., one on your laptop PC.)
For increased security, you can prefix the lines in the
~/.ssh/authorized_keys file with options that restrict access
to particular hosts. For instance, Joe Wells might prefix the key he uses
from Glasgow with the option
from="*.dcs.gla.ac.uk,130.209.240.*"
separating it from the rest of the line by a space. See the
sshd man page.
The instructions above for setting up to work remotely suggest that you
use the ssh-agent-setup script, which avoids proliferation of
authentication agents and minimizes the number of times that you need to
type your SSH passphrase in any login session.
An alternative scheme, if you use the X window system, is to start your X
server or window manager under the aegis of the
ssh-agent command. For example, if you have a
.xsession file or a similar script that starts your
window manager, then change it by prefixing the window manager
startup command line with ssh-agent (followed by a
space). Then, at the start of any login session, just issue the
ssh-add command (with no arguments) in any shell
window. This prompts for your passphrase, and establishes your
SSH identity for all processes that descend from the window
manager, e.g., for shell windows, editors, and so on.
The example command given above for filtering CVS status reports is
regrettably long for such a handy operation. Consider making an alias for
it. It pipes both standard output and standard error into grep
because the names of subdirectories come out on the latter. The
equivalent for Bourne-shell derivatives (such as bash) is
cvs status 2>&1 | grep -i status:
Whenever you commit changes to the repository, you should describe what
you've done. The -m option allows you to compose a brief log
message on the command line. You can also put your description in a file
and specify it to cvs commit by using
-F filename instead of -m. If you do
neither, your favorite editor will be started to receive your message.
The change description you supply will be recorded with each file that
has been changed. Sometimes it's preferable to commit selectively in
order to customize the log message to a particular group of files.
References
Secure Shell (ssh)
Secure Shell (ssh) is a drop-in replacement for UNIX
rsh. Because ssh encrypts communication,
sites like BC that have disabled rsh for security
reasons are able to allow remote access via ssh. See
the ssh home page for
general information. You can also consult the UNIX man
pages on ssh, ssh-keygen, ssh-agent,
and ssh-add.
Concurrent Versions System (CVS)
The Concurrent Versions System (CVS) is a version control system that allows
multiple users to work on the same source files simultaneously. To support
distributed development, it allows remote access via network to a central
repository. See
CVS Bubbles for
links to information about CVS. The manual is available as
hypertext
and it should also be accessible using Emacs's M-x info
command. (At BC, the CVS manual is in the default info menu. At
BU, use C-u M-x info and respond with
~church/info/cvs.info at the prompt.)
