BCS_SOI(1)
NAME
bcs_soi - the Baseline Configuration System (BCS) for SOI
SYNOPSIS
N/A
DESCRIPTION
BCS is a set of utilities for maintaining a single baseline
and multiple staging areas for a software development
effort. BCS provides some configuration management func-
tionality as well as the means for multiple users to work
concurrently on a common source tree with minimal conflict.
The baseline directory is /home/soi/CM which is owned by CM.
When you follow the directions in DETAILED DISCUSSION below
you will have your own staging area that "looks into" the
baseline.
SUMMARY OF USE
sync_staging [-r] directory
Syncronize a staging directory with the baseline.
bcsco file
Check out and lock a file. You can now edit the file.
register_file file
Register a new file with BCS. This makes a new file
known to BCS and checks it out and locks it for you.
rcsfix file
Adds the rcs id strings to the file. Detects which type
of file it is and adds the appropriate strings. For a
.c file make sure that you edit below the char rcsid[]
string.
bcsci file
Check in and unlock a file. A read-only copy is left in
your directory. This updates the file in the RCS direc-
tory in the baseline corresponding to the staging
directory that the command is done from. Other users do
not see the updated file but will get it if they check
it out.
update_baseline file
Updates the file in the baseline directory correspond-
ing to the latest version of the file in the RCS direc-
tory. This allows all users to now see the file that
you have just checked in.
stage file
Removes the link of the file into the baseline and
copies the actual file into your directory. The file is
still read-only. If you want to edit it you must check
it out.
unstage file
Replaces the file with a link into the baseline. This
is normally used when you have your own copy of a file
but want to restore it the the copy in the baseline,
for example, abandon your own copy of an executable.
You will be warned if you have checked out the file. If
you override the warning you will get the link to the
baseline version of the file, but the file will still
be locked by you.
bcs_info file
Provides various information about what BCS detects as
the state of the file.
lslocked [-r] [-Uname] directory
This is a perl script. It lists all the rcs checked out
files (i.e. locked) in the given directory. [-r] is
recursively, [-Uname] is for the particular user's
name. The default directory is ".".
DETAILED DISCUSSION
CREATING THE STAGING AREA:
* Each user must be a member of the group "SOI".
* Each user must do a "mkdir STAGING" in their home direc-
tory or some appropriate place. The full path name of this
directory that you have just made (for example,
/home/you/STAGING) is refered to as "staging_directory"
below, so wherever you see the word "staging_directory" sub-
stitue, for example, /home/you/STAGING.
* Call "/home/jim/STAGING/stage_setup staging_directory".
You MUST specify the full path name of the
staging_directory. This will create a .bcsinit and a
.baseline_path file in the staging_directory.
* At the end of your .cshrc, source the .bcsinit file in the
staging_directory. This should be done at the end of your
file because it should override variables that you may
already have set, such as $MKROOT.
* In your path, define staging_directory/bin/_$MACHINE. Make
sure that you remove any /home/soi/new/bin/_$MACHINE from
your path.
* cd to your staging_directory and do "sync_staging -r ."
This will syncronize your staging area with the baseline.
The CM will notify everyone if it becomes necessary to ever
do this again. In any event you may do this at any time with
no harm.
* NOTICE! On fault make sure that your rcs is the
/usr/local/bin one. The /usr/sbin/rcs does not pass the BCS
regression tests.
USING THE STAGING AREA:
After you have done the above your staging area is
ready for use. You only work in your staging area. No one
cd's to any /home/soi/CM directory. The baseline belongs to
the Configuration Manager. Your staging area
will initially have links to everything of importance in the
baseline. When you want to edit something you must first
check it out from the baseline by saying:
%bcsco file_name
bcsco is an alias for the correct bcs version of the
rcs checkout command with a standardized lock flag. You
never use the rcs commands directly.
If someone else has already checked it out, you will
not be able to get it. You will be told who has already
checked it out. If you do not check it out you will not be
able to edit it as it will be read only.
You edit the file as you want and do a make on your
taget. The objects and the new executable are local in your
staging area. No one else will see them. When you're happy
that it's all ok, you check back in your file with:
%bcsci file_name
This removes your lock on the file and makes it read
only again. A local copy is retained so that you do not have
to check it out again to view the file. This updates the RCS
log of your file so that the next person checking it out
will see your changes. The .c file in the baseline is not
updated until you do an update_baseline. Only the CM will
see this .c file. It's not really necessary for you to
update the baseline as the CM will get all of the latest
stuff from the RCS directories before they make. In practice
it might be a good idea to let the CM see the latest stuff
without having to do anything explicit. However as we learn
as we go, we may decide elsewise. So for now let's say that
you do an update_baseline.
You update the baseline by saying:
%update_baseline file_name
You can wait to check in and update the baseline until
you have completed a set of files that are related. Coopera-
tion is required in that you don't check out a popular file
and then sit on it.
If you are creating a new file, first do:
%register_file file_name
This will create a the file in the baseline if it
doesn't already exist and lock it for you. Then put in the
rcs ident information by:
%rcsfix file_name
Now edit you file normally, and make sure that for a .c
file you start your edit just below the first line that has
the char rcsid[] definition. When you have completed the
file do the bcsci and update_baseline. You may do a
register_file if the file already exits in your staging
area, however it is good practice to do the register_file
first in order to reserve that file name amongst all the
users. The CM must initially set up any new directories.
If you have checked out a file and later decide that
you don't want to change anything, but want to remove your
lock on it, just do another bcsco and answer yes on the
overwrite warning, and then check it back in.
Notice that when you update the baseline with a new .c
file you have not changed the baseline executables. This
can only be done by the CM. When everyone has agreed that
they have submitted everything for the next SOI version,
then the CM does the master build in the baseline. Option-
ally the CM may also be requested to make a new library for
example, that people may need to do their new version
development. If the new library is a flop, the CM has a way
of remaking the previous one.
NOTES:
* The man pages are under RCS but do not have a $Log ident,
as this will be displayed on the man page.
* The lib make files have been modified to make locally and
do a mv to the target. This is as done in other make files
and is needed for our BCS implementation.
* Keep an eye out for any expilict reference to
/home/soi/new that was used instead of $MKROOT.
* Forward all pathology reports to CM.
SEE ALSO
BCS: A Baseline Configuration System Version 2.0 beta Jan
10, 94 RCS - A System for Version Control Jan 3, 91
/usr/local/man/man1/bcs.1
AUTHOR
Jim Aloise
HISTORY
1994-11-10 SOI Version 0.9