<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>Coda File System User and System Administrators Manual: Coda Source Layout </TITLE>
<LINK HREF="manual-15.html" REL=next>
<LINK HREF="manual-13.html" REL=previous>
<LINK HREF="manual.html#toc14" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-15.html">Next</A>
<A HREF="manual-13.html">Previous</A>
<A HREF="manual.html#toc14">Contents</A>
<HR>
<H2><A NAME="SourceLayout"></A> <A NAME="s14">14. Coda Source Layout </A></H2>
<P>This chapter is a guide to using and modifying Coda source code at CMU-SCS.
It is mainly intended to help new members of the project come up to speed.
But it may also help sites outside CMU that receive a Coda distribution to
devise procedures appropriate to their environments.
<P>
<H2><A NAME="ss14.1">14.1 The Big Picture</A>
</H2>
<P>All files relating to Coda, with the sole exception of RCS files (see Section
<A HREF="#RCS">XXX</A>), are stored in <CODE>/coda/project/coda.</CODE>
Let's call this <CODE>$CODA</CODE>.
The directories under <CODE>$CODA</CODE> correspond to different <EM>releases</EM> of Coda, such as
<CODE>alpha,</CODE> <CODE>beta,</CODE> and so on. A release is a complete set of <EM>mutually consistent</EM>
sources, libraries and binaries. "Mutually consistent" means, for example, that the
Venus and server from a release will work with each other. It also means that you can
freely use the libraries and include files to compile new binaries in that
release. @ux[There are no guarantees of any kind across releases.]
<P>Before a new instance of a release is made, careful thought must be given as to how current
users of that release will be affected. Will all such users have to be upgraded in one
fell swoop? Or can they switch over at their own leisure? As the deployed Coda system grows,
upgrading everyone in one fell swoop gets harder. After all, some of the users may be in hiding
with their disconnected laptops!
<P>By convention, the <CODE>omega</CODE> release corresponds to the version of Coda in production
use. Most users Venii, as well as the servers on production machines,
are from this release. Hence the value of <CODE>/usr/coda/SYMLINK</CODE> on those users workstations
is <CODE>$CODA/omega</CODE>.
<P>
<H3>How versions evolve</H3>
<P>
<P>The <CODE>alpha</CODE> release of software corresponds to a lightly tested version of the system.
Individual developers have done a significant amount of testing of <CODE>alpha</CODE> software, but
it hasnt yet been stressed heavily, nor has it been tested in real use. Hence <CODE>alpha</CODE>
server code should not be run on servers that hold real user data. They should only be
run on the <CODE>alpha</CODE> servers (also known as "test" servers). Similarly for other <CODE>alpha</CODE>
software. When you are doing code development, you
usually pick up include files and libraries from the <CODE>alpha</CODE> release. Thus, the
private versions of software you build is, at best, of <CODE>alpha</CODE> quality.
<P>The <CODE>beta</CODE> release corresponds to a version of the system that is expected to be released
soon for production use.
A small number of users, typically members of the Coda project, depend upon
this release. Actual use by such users is part of the testing of the <CODE>beta</CODE>
release. Eventually, when we have enough confidence in the stability and correctness of
the <CODE>beta</CODE> release, we promote it <CODE>omega.</CODE>
<P><CODE>beta</CODE> is really a symlink to a volume mount point <CODE>beta-<unique></CODE>,
where <CODE><unique></CODE> is an identifier made up by the <CODE>makebeta</CODE> script described below.
Upgrading the <CODE>beta</CODE> release consists of creating a new volume, mounting it
at <CODE>beta-<unique></CODE>, populating it using the steps described in Section
<A HREF="#alphatobeta">XXX</A>,
and finally changing the <CODE>beta</CODE> symlink to point to <CODE>beta-<unique></CODE>.
The old <CODE>beta</CODE> volume is preserved for a while, until is clear
that the new release hasnt triggered any serious problems. It can then be purged
to reclaim space, or recycled for a future beta release.
<P><CODE>omega</CODE> is also a symlink to a volume mount point <CODE>beta-<unique></CODE>.
After a <CODE>beta</CODE> release has been running robustly for a while, it is upgraded
to <CODE>omega</CODE> by merely changing the value of the <CODE>omega</CODE> symlink. No recompilation
is involved.
<P>When a <CODE>beta-<unique></CODE> release is created, the <CODE>makebeta</CODE> script creates an RCS branch
named <CODE>beta-<unique></CODE> for every file in the release.
Normally no development or changes are done along this branch.
However, it provides a way to introduce an emergency fix
in a <CODE>beta</CODE> or <CODE>omega</CODE> release if the need ever arises.
<P>
<H3>How code is developed</H3>
<P>
<A NAME="CodeDevelopment"></A> <P>Lets illustrate this with a specific example. Suppose I want to upgrade the module
<CODE>rpc2</CODE> and build a new Venus to use the upgrade. I begin by creating two
private directories, say <CODE>/coda/usr/satya/src/rpc2</CODE> and <CODE>/coda/usr/satya/src/venus</CODE>,
and populating them with source files from the <CODE>alpha</CODE> release of these two modules.
Section
<A HREF="#RCS">XXX</A> tells you how this step actually gets done. Now I proceed to modify files in
<CODE>rpc2</CODE> and to compile and test the module using standalone test programs.
Then I modify files in <CODE>venus</CODE> to use the upgrade and then build a Venus.
When building Venus, I must make sure that the version of <CODE>rpc2</CODE> used is the one I just built.
Section
<A HREF="#Changes">XXX</A> tells you how to do this. Now I have a Venus that I can test.
As bugs are found in the new Venus, I iterate the above procedure.
When I am confident that my changes to <CODE>rpc2</CODE> and <CODE>venus</CODE> are right, I update the <CODE>alpha</CODE>
release of these two modules.
<P>The process of updating the <CODE>alpha</CODE> release is known as <EM>installation.</EM>
Installation is the point at which work done by a Coda project member
becomes visible to others in the project. Prior to this point, all work is done in
that users own private directory.
Installation always occurs at the granularity of entire <EM>modules.</EM> In other words, one never
installs an individual library, include file, etc. Rather the entire source code for a module and
all relevant files compiled from it are installed together. Modified files are automatically
checked into RCS as part of the installation procedure.
At some future time, these changes along with many others that were installed
will make it into a <CODE>beta</CODE> release. Section
<A HREF="#PromotingReleases">XXX</A> shows you how
this is done. After some use as <CODE>beta</CODE>, it will be promoted to <CODE>omega</CODE>.
<P>
<P>
<H2><A NAME="ss14.2">14.2 Layout of Source Code</A>
</H2>
<P>
<H3>Layout of a Release</H3>
<P>Each release has the structure shown in Figure
<A HREF="#ReleaseLayout">XXX</A>. Note that this layout
is identical for all releases.
<P>
<FIGURE>
<EPS FILE="coda-releases-fig">
<CAPTION>Structure of a Coda Release
<A NAME="ReleaseLayout"></A> </CAPTION>
</FIGURE>
<P>Underlined names are symlinks to machine-specific directories. On a 386
machine for example, <CODE>bin</CODE> is a symlink to <CODE>i386_mach/bin</CODE>.
Although only two machine-specific directories (<CODE>pmax_mach</CODE> and
<CODE>i386_mach</CODE>) are shown, there can be many more.
<P>The source tree for the release is in <CODE>src</CODE>. A copy of the header
files from <CODE>src</CODE>
is in <CODE>include</CODE>. Both <CODE>src</CODE> and <CODE>include</CODE> are machine-independent. For each
supported machine type, there is a directory containing binaries (<CODE>bin</CODE>) and libraries (<CODE>lib</CODE>).
The source tree in a release is fully self-contained. In other words, if you started out with empty
<CODE>include,</CODE> <CODE>lib,</CODE> and <CODE>bin</CODE> directories, you could completely populate them by compiling
the source code in <CODE>src</CODE>. The only exception to this are the files in <CODE>include-special,</CODE>
<CODE>lib-special,</CODE> <CODE>src-special,</CODE> and <CODE>bin-special</CODE>. These directories contain a very small number of files
that have to be copied in by hand. The sources for these files are not in <CODE>src</CODE>.
<P>
<P>
<H3>Layout of the source directory</H3>
<P>The <CODE>src</CODE> directory in each release is organized as in Figure
<A HREF="#SrcLayout">XXX</A>. The <CODE>MAKECODA</CODE>
script simplifies the compilation of the entire release. The <CODE>Makeconf</CODE> file defines in
a single spot many key variables and paths used by the makefiles in individual modules. Those
makefiles inherit these definitions automatically, when the CMU-SCS <CODE>make</CODE> is used.
The <CODE>SOURCEME</CODE> file contains a minimal set of environment definitions. By sourcing this
file before you compile anything, you can be sure that you arent obtaining binaries, libraries
etc. from non-standard places. This is especially important if your <CODE>.login</CODE> or <CODE>.cshrc</CODE>
files define elaborate <CODE>PATH, CPATH, LPATH</CODE> variables.
<P>
<FIGURE>
<EPS FILE="coda-src-fig">
<CAPTION>Structure of the source directory in a release
<A NAME="SrcLayout"></A>
</CAPTION>
</FIGURE>
<P>Underlined names are symlinks to RCS directories. For example,
<CODE>RCSLINK</CODE> is a symlink to <CODE>/afs/cs/project/coda/rcs</CODE>;
<CODE>auth2/RCS</CODE> is a symlink to <CODE>../RCSLINK/auth2</CODE>; and so on.
Indirecting via <CODE>RCSLINK</CODE> makes it simple to relocate the RCS
directories without changing lots of individual symlinks. Such relocation
might happen, for example, when Coda sources are used outside CMU.
<P>
<H3>Layout of a typical module</H3>
<P>The structure of a typical module is shown in Figure
<A HREF="#ModuleLayout">XXX</A>.
<P>
<FIGURE>
<EPS FILE="coda-module-fig">
<CAPTION>Typical module structure
<A NAME="ModuleLayout"></A> </CAPTION>
</FIGURE>
<P>In this particular module, <CODE>rpc2</CODE>, the underlined name RCS indicates a
symlink to <CODE>../RCSLINK/rpc2</CODE>. Indirection via <CODE>RCSLINK</CODE> makes
relocating the RCS directories a simple matter.
<P>Notice that only the source files are located in this directory; there are no object
files. The CMU-SCS <CODE>make</CODE> facility puts all compilation targets elsewhere, thus
allowing the source directory to be readonly. This has two advantages. First, the
source directories are uncluttered. Second, it simplifies building Coda for multiple
machine types, since the target directories can be different for each machine type.
<P>Also notice the presence of multiple makefiles in this module. Although this is not
characteristic of all Coda modules, it is typical of some. The true dependencies are
capture in <CODE>Makefile.real</CODE>, and the others, like <CODE>Makefile.coda</CODE> and <CODE>Makefile.misc</CODE>
invoke <CODE>Makefile.real</CODE> after defining environment variables appropriately. This simplifies
the use of these modules outside Coda. If you are compiling by hand, you have to say
"<CODE>make -f Makefile.coda <target></CODE>", rather than just "<CODE>make <target></CODE>".
<P>
<P>
<H2><A NAME="ss14.3">14.3 Module Dependencies</A>
</H2>
<P>
<A NAME="Dependencies"></A> <P>Most Coda modules rely on files installed by other Coda modules. It is
therefore important to install modules in the correct order.
Otherwise you could get yourself into real trouble. If you are
compiling from scratch, the out-of-order installations will simply fail.
But if you are modifying an existing release, you could end up
with mysterious bugs because obsolete versions of header files and libraries
may be used.
<P>You are @ux[strongly] urged to use the script <CODE>MAKECODA,</CODE> described in Section
<A HREF="#MAKECODA">XXX</A>.
The correct precedences of modules are wired into the script, so you dont have to
deal with them.
<P>For the curious, the correct order of compilation of modules is given below.
In principle, modules of the same precedence (i.e. in the same set) can be compiled in
parallel. But I havent actually tried that yet.
<P>
<OL>
<LI><CODE>scripts</CODE> Miscellaneous scripts, including <CODE>alphaci</CODE> on which intalls of all other modules rely </LI>
<LI>
<UL>
<LI><CODE>mlwp</CODE> Lightweight process package </LI>
<LI><CODE>dir</CODE> Directory package used by Venus and server </LI>
<LI><CODE>sys</CODE> Miscellaneous routines </LI>
<LI><CODE>sunrpc</CODE> Sun Microsystems public domain XDR code and interface for device driver/venus interaction </LI>
<LI><CODE>igmp</CODE> Internet multicast support for old RFC
(dummied out currently; someone should fix these to use the new RFC) </LI>
<LI></LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>util</CODE> Utility routines </LI>
<LI><CODE>rpc2</CODE> RPC package </LI>
<LI></LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>camstuff</CODE> Header files that allow runtime choice of RVM or VM for persistence on servers </LI>
<LI><CODE>blurb</CODE> Program to adjust copyrights </LI>
<LI><CODE>pdbstuff</CODE> Protection database management </LI>
<LI><CODE>rp2gen</CODE> Stub generator for RPC2 </LI>
<LI><CODE>comm</CODE> Communication layer above RPC2 for connection management (not yet in use) </LI>
<LI><CODE>libal</CODE> Access list package. </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>vicedep</CODE> Header files and RPC2 interface definition files put here to break circular dependencies </LI>
<LI><CODE>fail</CODE> Network failure and variable speed emulator </LI>
<LI><CODE>auth2</CODE> Authentication server </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>login</CODE> Implements clog, cunlog, ctokens, etc. </LI>
<LI><CODE>cfs</CODE> The VFS driver; most of this code is linked into the Mach kernel </LI>
<LI><CODE>vv</CODE> Version vector routines </LI>
<LI><CODE>mond</CODE> Coda usage data collector </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>resolve</CODE> Library used by repair (should get integrated into <CODE>repair</CODE>) </LI>
<LI><CODE>vol</CODE> Volume package used by server </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>res</CODE> VM-based directory resolution algorithms </LI>
<LI><CODE>repair</CODE> Repair tool </LI>
<LI><CODE>venus</CODE> Cache manager </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>volutil</CODE> Volume utilities </LI>
<LI><CODE>vtools</CODE> Miscellaneous Venus tools </LI>
<LI><CODE>rvmres</CODE> RVM-based directory resolution algorithms </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>vice</CODE> Server code </LI>
</UL>
</LI>
<LI>
<UL>
<LI><CODE>update</CODE> The daemon which updates server databases </LI>
<LI><CODE>norton</CODE> A Coda server, RVM debugger </LI>
<LI><CODE>asr</CODE> Application Specific Resolver package </LI>
<LI><CODE>egasr</CODE> ASR examples@end)annote</LI>
</UL>
</LI>
</OL>
<P>
<P>
<P>
<H2><A NAME="ss14.4">14.4 Building a Release</A>
</H2>
<P>
<P>
<H3>Prerequisites</H3>
<P>
<A NAME="Prerequisites"></A>
To compile Coda "out of the box" you need the following compilation tools:
<UL>
<LI>Gnu g++ compiler version 2.5.8 or higher.</LI>
<LI>CMU-SCS <CODE>make</CODE> The makefiles in the Coda sources exploit many of the enhancements
made by CMU to Unix make. Conditional macro expansion, the ability to place targets
in a different place from the sources, and the inheritance of variable definitions from
Makeconf are the three major features we rely on.</LI>
<LI>C compiler on IBM-RTs It is important that the compiler be set to use <CODE>long</CODE> to represent <CODE>enum</CODE>.
The RT C compilers default behavior of using <CODE>char</CODE> to represent small-valued enums will
cause insidious problems in RPC2 communication. On CMU-SCS machines this is done by defining the
environment variable <CODE>PLAINC</CODE> to be <CODE>/usr/misc/.hc/bin/hc2</CODE>. The <CODE>MAKECODA</CODE> script does this
automatically for you, but you must remember to do this manually if you arent using it. (Some <CODE>.login</CODE>s have the variable <CODE>ccC</CODE> defined to <CODE>hc</CODE>; you must delete this definition
also).</LI>
</UL>
<P>It should be possible to modify the code to use other versions of C++
(such as <CODE>g++</CODE>), or to use standard Unix make. But we havent
tried this, and dont plan to.
<P>
<H3><A NAME="SpecialDirectories"></A> Special directories </H3>
<P>Before you can compile Coda, you need to populate the <CODE>{include,lib,bin,src}-special</CODE> directories.
These contain files that are (a) needed but arent in the Coda sources or (b) standard Mach header files, with slight modifications. The <CODE>MAKECODA</CODE>
script contains an up-to-date list of what these files should be. Here is
a list that was current at the time of writing this document:
<DL>
<DT><B>RVM files</B><DD><P>RVM is a lightweight transactional package that is used on
servers and clients. It is a package that is independent of Coda. The
current set of files from this package are:
<BLOCKQUOTE><CODE>
<PRE>
include-special/{rvm.h,rvm_lwp.h,rvm_statistics.h,
rvm_segment.h,rds.h}
lib-special/{librvm.a,librvmlwp.a,libseg.a,librds.a}
bin-special/{rdsinit,rvmutl}
src-special/{Makeconf,Makefile,READ_ME,plumber,rds,
rvm,seg}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B>Tracing facility files</B><DD><P>These files pertain to a file-tracing
facility, <CODE>dfstrace</CODE>, used at CMU. To function as a
trace-driven simulator, Venus requires the following files:
<BLOCKQUOTE><CODE>
<PRE>
include-special/tracelib.h
lib-special/libtrace.a
</PRE>
</CODE></BLOCKQUOTE>
If you don't intend to use Venus as a simulator, you could construct a dummy <CODE>libtrace.a</CODE> with
empty routines to avoid unresolved references. You do need <CODE>tracelib.h</CODE> though.
<DT><B>Plumber</B><DD><P><CODE>malloc</CODE> The Coda makefiles allow you to build versions of <CODE>venus</CODE> and <CODE>codasrv</CODE>
that use a special <CODE>malloc</CODE> to help detect memory leaks. The following files are needed
for this:
<BLOCKQUOTE><CODE>
<PRE>
include-special/newplumb.h
lib-special/{libplumber.a,libnewplumb.a}
</PRE>
</CODE></BLOCKQUOTE>
If you don't plan to build the plumbing facilities, you can just create zero-length files with
these names to keep the <CODE>MAKECODA</CODE> script happy.
<DT><B>Modified Mach headers</B><DD><P>The changes in these files had to be made
because of compilation errors
from C++, or (as in the case of <CODE>assert.h</CODE>) to define different behavior for standard macros:
<BLOCKQUOTE><CODE>
<PRE>
include-special/{assert.h,cthreads.h,setjmp.h,sys/inode.h,
i386/fpreg.h,i386_mach/endian.h}
</PRE>
</CODE></BLOCKQUOTE>
</DL>
<P>
<H3><A NAME="MAKECODA"></A> Using the MAKECODA script </H3>
<P>
<P>Once you have taken care of the prerequisites and special files, you can compile a release.
The simplest way to do this is to run the <CODE>MAKECODA</CODE> script in <CODE>src</CODE>.
This script takes one required and two optional arguments.
The required argument is <CODE>OBJECTDIR</CODE>, which is the pathname of
the directory where the object files should be placed. It is sensible to specify a different
directory for each machine type, and the <CODE>@@sys</CODE> facility of AFS and Coda lets you do this.
<P>So, for example, to compile the <CODE>beta</CODE> release, I would do the following:
<P>
<BLOCKQUOTE><CODE>
<PRE>
cd /coda/project/coda/beta/src
./MAKECODA OBJECTDIR=/coda/usr/satya/OBJS/@@sys
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>MAKECODA</CODE> script will first check to make sure that all necessary
special files are present. If any are missing it will prompt you. It then
goes through the Coda modules in the correct order and does a <CODE>make install</CODE> on each. The usual checkin to RCS that is done by
<CODE>alphaci</CODE> as part of <CODE>make install</CODE> (see Section
<A HREF="#alphaci">XXX</A>) is supressed.
If all goes well, everything in Coda will be compiled, and the <CODE>bin</CODE>, <CODE>lib</CODE>,
and <CODE>include</CODE> directores will be populated. You will have to repeat this once
for each machine type.
<P>Sometimes, you will run into a problem part-way through <CODE>MAKECODA</CODE>. After you
have fixed the problem, youd probably like to continue where you left off rather
than redoing everything from the beginning. Hence <CODE>MAKECODA</CODE> lets you specify
the name of the module to start from. Here is an example:
<BLOCKQUOTE><CODE>
<PRE>
./MAKECODA OBJECTDIR=/tmp/@@sys FIRSTMODULE=vol
</PRE>
</CODE></BLOCKQUOTE>
<P>Finally, the pathname of the root of the release you are compiling is specified by
the variable <CODE>ROOT</CODE> in <CODE>MAKECODA</CODE>. You can change this by editing <CODE>MAKECODA</CODE>,
and this is in fact what the <CODE>makebeta</CODE> script does for you when you create a new release.
But you can also override it on the command line thus:
<BLOCKQUOTE><CODE>
<PRE>
cd /tmp
MAKECODA OBJECTDIR=/tmp/@@sys ROOT=/coda/project/coda/alpha
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss14.5">14.5 Making Incremental Changes</A>
</H2>
<P>
<A NAME="Changes"></A> <P>Once the <CODE>alpha</CODE> release has been built, you can start code
development. We have already seen the general procedure in Section
<A HREF="#CodeDevelopment">XXX</A>. Lets look at an example in more detail.
<P>Suppose I am working on the module <CODE>vtools</CODE> and need to change
the files <CODE>cmon.c</CODE> and <CODE>codacon.c</CODE>. Heres what I would do:
<BLOCKQUOTE><CODE>
<PRE>
# Create a scratch directory for my work
mkdir /coda/usr/satya/src
cd /coda/usr/satya/src
# Set up links to RCS directory, and root of release
ln -s /afs/cs/project/coda/rcs/coda-1.0 RCSLINK
ln -s /coda/project/coda/alpha/src SRCROOT
ln -s SRCROOT/Makeconf
# Create directory for this module
mkdir vtools
cd vtools
ln -s ../RCSLINK/vtools RCS
# Lock and checkout the file (s) to be modified
rcsco -l cmon.c codacon.c
# Now edit cmon.c and codacon.c
# Then compile this module
# Source the standard environment file to make sure your
# compilation environment (PATH, LPATH, CPATH, etc.) is set up right
source ../SRCROOT/SOURCEME
make OBJECTDIR=/coda/usr/satya/OBJS/@@sys cmon codacon
# Test cmon & codacon, then iterate on edit/debug cycle above
# Now you are ready to install your changes.
# You must first create a file called RCSMSG, and enter text
# in it that will become the RCS log message for the checkin.
# It will also be posted to the changelog bboard, so that
# others in the group will know of your installation
echo "Fixes to annoying bugs ... blah blah blah ..." > RCSMSG
make OBJECTDIR=/coda/usr/satya/OBJS/@@sys install
# You are now done!
# The install step automatically released the write locks on cmon.c
# and codacon.c
# Repeat the install step for each of the other supported platforms.
</PRE>
</CODE></BLOCKQUOTE>
<P>Notice that many other files may be need for compilation,
but you dont have to check them out. This is because the CMU-SCS
make knows to check out any needed files automatically into the compilation
target area.
<P>
<H3>The alphaci script</H3>
<P>
<A NAME="alphaci"></A> <P>The automatic checkin is done by a script called <CODE>alphaci</CODE> that is invoked
as the last step of <CODE>make install</CODE>. <CODE>alphaci</CODE> will give you an error if
the <CODE>RCSMSG</CODE> file is missing; it moves it to <CODE>RCSMSG.old</CODE> once it has
checked in files. <CODE>alphaci</CODE> is smart enough to discover new files that
arent mentioned in RCS, and prompts you to ask if you want them checked in
too. Often you may not want this, because the files in question were just
test files created for debugging. <CODE>alphaci</CODE> assumes that only writable
files should be checked in; it prompts you about what to do with files that
are not writable.
<P>The RCSMSG file is also used by <CODE>alphaci</CODE> for posting on the changelog bboard (<CODE>cmu.cs.proj.coda.changelog</CODE> at CMU). You should follow the posts on this
bboard closely, so that you are aware of changes to Coda modules by other
project members. Here are some typical posts from the bboard:
<BLOCKQUOTE><CODE>
<PRE>
03-Feb-93 18:56 M Satya Installed scripts for IBMRT
Posted by alphaci from STRAUSS.CODA.CS.CMU.EDU
No files checked into RCS
03-Feb-93 18:50 M Satya Installed scripts for I386
Posted by alphaci from WEBER.CODA.CS.CMU.EDU
No files checked into RCS
03-Feb-93 18:22 M Satya Installed scripts for PMAX
Posted by alphaci from MOZART.CODA.CS.CMU.EDU
Files checked into RCS: Makefile makebeta restartserver restore.sh
RCS message follows:
Created new script, makebeta, to make a clone of the entire alpha
source tree, and to create branches in RCS for all files.
</PRE>
</CODE></BLOCKQUOTE>
Notice how the installations for machine types I386 and IBMRT caused no RCS
files to be checked in. This is because the installation for the first machine
type, PMAX, did the checkin.
<P>
<P>
<H2><A NAME="ss14.6">14.6 Promoting Releases</A>
</H2>
<P>
<A NAME="PromotingReleases"></A> <P>As we have seen earlier, there are 3 important releases of software:
<CODE>alpha,</CODE> <CODE>beta,</CODE> and <CODE>omega</CODE>. Servers are also classified
by this scheme. At the time of writing this document, there were
3 <CODE>omega</CODE> servers (<CODE>rossini</CODE>, <CODE>puccini</CODE>, and <CODE>scarlatti</CODE>),
3 <CODE>beta</CODE> servers (<CODE>grieg</CODE>, <CODE>haydn</CODE>, and <CODE>wagner</CODE>), and
4 <CODE>alpha</CODE> servers (<CODE>schumann</CODE>, <CODE>gershwin</CODE>, <CODE>mahler</CODE>, and <CODE>vivaldi</CODE>).
<P>The <CODE>omega</CODE> servers hold real data, so software let loose on them should
have been tested very well. Having to reinitialize and to restore many gigabytes on
the <CODE>omega</CODE> servers because of storage corruption is not an experience
you are likely to forget! The <CODE>beta</CODE> servers hold some real data, but
the number of users depending on that data is restricted to a few Coda project
members. Further, that data is of a kind that can be easily reconstructed.
The <CODE>alpha</CODE> servers are used by project members for testing.
Obviously, only one person can test their software on a server at a time, so you
should coordinate use of the servers with the other members.
<P>
<H3>Promoting alpha to beta</H3>
<P>
<A NAME="alphatobeta"></A> <P>When the <CODE>alpha</CODE> release has diverged substantially from <CODE>beta</CODE>,
and is relatively stable, we will decide to make a new <CODE>beta</CODE> release.
One member of the Coda project will serve as <EM>release coordinator</EM> for the promotion.
<P>
<P>The first step in this process is for the release coordinator to post on
<CODE>cmu.cs.proj.coda.general</CODE>, asking project members to checkin changes and to drop
all RCS locks on the main line of development by a certain deadline.
As soon as possible you should release all mainline locks. It is ok to
hold on to locks on private branches. Once the deadline expires, the release
coordinator will feel free to break mainline locks.
<P>In the second step, the release coordinator runs the <CODE>makebeta</CODE> script to
create a clone of the current state of <CODE>alpha</CODE>. <CODE>makebeta</CODE> first
synthesizes a unique identifier of the form <EM>date_xxxxx</EM> where <EM>xxxxx</EM> is
the number of seconds since midnight. The name of the new release is then
<CODE>beta-<unique identifier></CODE>; for example, <CODE>beta-3Feb1993_43696</CODE>.
This name is used to tag a new RCS branch for every file in the release,
so that emergency fixes are possible long after the <CODE>alpha</CODE> release has
diverged from this <CODE>beta</CODE> release.
<P>The <CODE>makebeta</CODE> script works as follows:
<UL>
<LI>First, it constructs a unique
name for the release, as described above. It then pauses, waiting for the
user to construct a directory with this name. Usually, the release coordinator
makes this name the mount point of a new volume. <CODE>makebeta</CODE> checks to make
sure the directory is empty before proceeding, to avoid accidental clobbers.
For brevity, we refer to this directory as <CODE>$BETA</CODE>.</LI>
<LI>Second, <CODE>makebeta</CODE> looks at <CODE>/coda/project/coda/alpha/src</CODE> (<CODE>$ALPHA/src</CODE>, for short)
and determines the names of the modules in it.</LI>
<LI>Third, it makes a copy of the <CODE>$ALPHA</CODE> modules in <CODE>$BETA</CODE>. In making this copy,
it actually checks out the files (unlocked) from RCS, and compares them with <CODE>$ALPHA</CODE>.
This is a sanity check, to ensure that RCS and <CODE>$ALPHA</CODE> are in sync. One side effect
of this comparison is to detect RCS locks.</LI>
<LI>If any locks were detected, or if any files in RCS differed from their copies in
<CODE>$ALPHA</CODE>, <CODE>makebeta</CODE> pauses and asks the user to go take a look at whats wrong.
It then asks the user whether to proceed.</LI>
<LI>Next, <CODE>makebeta</CODE> creates a new RCS branch, named after this release, and re-checks
out files from the branch so that <CODE>$Header$</CODE> in those files is correctly set.</LI>
<LI>At this point, the files <CODE>MAKECODA</CODE> and <CODE>Makeconf</CODE> at the top level of <CODE>$BETA</CODE>
are edited by <CODE>makebeta</CODE> so that all references to <CODE>$ALPHA</CODE> are changed to <CODE>$BETA</CODE>.</LI>
<LI>Finally, <CODE>makebeta</CODE> copies over all the special directories (<CODE>{lib,bin,src,include}-special</CODE>).</LI>
</UL>
<P>The above procedure is quite slow, since many RCS interactions are involved. It usually takes
a few hours. If all goes well, <CODE>makebeta</CODE> requires little babysitting.
Note that the script does no locking. In other words, the <CODE>$ALPHA</CODE> tree better remain
frozen for the entire duration of the promotion.
<P>In the third step, the release coordinator <CODE>cd</CODE>s into <CODE>$BETA/src</CODE>, and runs <CODE>MAKECODA</CODE>
once for each machine type. Note that he doesnt have to specify anything other than <CODE>OBJECTDIR</CODE>,
since <CODE>makebeta</CODE> has already set <CODE>ROOT</CODE> correctly in the <CODE>MAKECODA</CODE> script. This step
guarantees that the binaries in <CODE>$BETA</CODE> were indeed compiled from the sources in <CODE>$BETA</CODE>.
<P>In the final step, the release coordinator makes the symlink <CODE>beta</CODE> point to <CODE>$BETA</CODE>.
This is the "commit" step that blesses the newly-cloned release as the <CODE>beta</CODE> release.
<P>
<H3>Promoting beta to omega</H3>
<P>
<P>After the <CODE>beta</CODE> release has been stressed for some time,
it will be promoted to <CODE>omega</CODE>. This is a much simpler procedure than the
<CODE>alpha</CODE> to <CODE>beta</CODE> promotion. The release coordinator merely has to make the
symlink <CODE>omega</CODE> point to the <CODE>beta-xxxx</CODE> where <CODE>xxxx</CODE> is the unique
identity of the release being promoted. This "commit" step blesses what was
hitherto <CODE>beta</CODE> as <CODE>omega</CODE>
<P>
<H2><A NAME="ss14.7">14.7 Copyright Notices</A>
</H2>
<P>
<P>Since Coda is distributed outside CMU, it is important that
every source file contain a copyright notice. The <CODE>blurb</CODE> program
simplifies adding and changing copyright notices. <CODE>blurb</CODE> expects
to find the copyright notice is at the very beginning of a file, so make
sure you dont move it when modifying a file.
<P>The only modules without Coda copyright notices are <CODE>sunrpc,</CODE>
which is public-domain code from Sun, and <CODE>cfs,</CODE> which is mostly
Mach kernel code.
<P>Some files in Coda are derived from the 1986 version of AFS-2.0.
Since AFS-2.0 is owned by IBM, these files have an IBM copyright notice in
addition to the Coda copyright notice.
<P>When you modify a file or add a new file, you should pay attention
to the copyright notices. Here are some simple rules to follow:
<OL>
<LI>If you add new files, just include the Coda copyright notice.
By definition, new code is not derived from AFS-2.0 and should
not receive an IBM copyright notice.</LI>
<LI>If you modify an existing file, dont do anything with the copyright
notice. All else being equal, add new code to new files, or to existing
files without the IBM copyright notice. But use good judgement here
-- if it is clear that the correct home for a piece of code is a file with
an IBM copyright notice, go ahead and put it there.</LI>
<LI>If you make a substantial copy of a file with an IBM copyright notice
then the copy also acquires the IBM copyright notice. The
interpretation of "substantial copy" is, of course, subjective.
If you copy a variable declaration, it is not a "substantial copy".
If you copy a whole bunch of procedures or macros, it is definitely
a "substantial copy". </LI>
</OL>
<P>A simple way to think of this is that some files in Coda are "tainted"
(i.e., they are derived from AFS-2.0). Tainted files can infect other
files if enough of their innards are copied. Existing untainted files,
and new files, stay untainted forever.
In general, do your best to keep the number of tainted files to a minimum.
Note that this discipline regarding copyrights is not intended to be
onerous or constraining --- just common sense and a little self-discipline.
<P>
<H2><A NAME="ss14.8">14.8 Using RCS for Revision Control</A>
</H2>
<P>
<A NAME="RCS"></A> <P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
1. Branch overview
One common problem in managing large software projects comes
to play when there are several people working on the same sets
of files. RCS helps by providing per-file locking to guarantee
that no two users modify the same file at the same time. If
several users are modifying the same line of development,
however, this locking does nothing to guarantee that one users
changes in one file wont interfere with another users changes
in another file.
To combat this problem, RCS provides the notion of a "branch".
A branch is a separate line of development carried out in parallel
to the main line of development. Version found on branches have
more than two digits in their version numbers. All digits make up
the version number of an element on a branch. For example, version
1.2.1.1 is an element in the first branch off of version 1.2.
As branch numbers are hard to deal with, you are recommended to
assign symbolic names to branches.
2. How to use branch
For example, a typical command to create and name a branch would be
rcsci -b -nKUDO_STATISTICS foo.c
where KUDO_STATISTICS is a symbolic name of branch
* This command will create a branch named KUDO_STATISTICS
off the last version on the mainline of foo.c
If you would like to specify the version number of which the first
branch element is off, a command would be
rcsci -b -r1.2 -nKUDO_STATISTICS foo.c
where 1.2 is the version number of which the first
branch element is off
The name is assigned to the branch (not the branched element), so
the subsequent commands such as
rcsco -l -rKUDO_STATISTICS foo.c
will refer to the latest element in that line of development.
3. What I checked in using branch
I checked in the following files using branch with the symbolic name
"KUDO_STATISTICS".
vicedep/mond.rpc2
venus/ fso.h
fso0.c
fso1.c
hdb.c
sighand.c
venus.c
venus.private.h
venusresov.h
venusutil.c
venusvol.c
venusvol.h
venusvm.c
venusvm.h
vol_vsr.c
vproc.c
The purpose of the modifications is to collect session statistics
and send them to the mond data collector. Currently, venii built
with these files are running on Brahms and faust, safely (I think so).
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss14.9">14.9 Coding Tips</A>
</H2>
<P>
<PRE>
<TO BE COMPLETED>
</PRE>
<HR>
<A HREF="manual-15.html">Next</A>
<A HREF="manual-13.html">Previous</A>
<A HREF="manual.html#toc14">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
211238da6d926d1ca4390483bb29f586
>
files
>
31
