.TH chkclasses N "07 Mar 1994"
.SH NAME
chkclasses \- test class action scripts.
.SH SYNOPSIS
.B chkclasses
.BI \-b  basedir
.BI \-c  cmpdir
.BI \-p pkgdir
[
.BI \-a arch
]
[
\fB-C\fP|\fB-E\fP \fIclass\fP[,\fIclass\fP...]
]
[
.B \-rmxkvlq
]
.SH DESCRIPTION
.LP
.B chkclasses
automatically tests class action scripts used for upgrading  releases. 
For testing, chkclasses uses two directory trees derived from build proto areas.
The  basedir, or destination, is a previous release and the cmpdir, or
source, is the release currently under development.
.B chkclasses
creates a copy of the destination file for a class action scripts to work on.
After each script is executed, the modified destination file is compared with
the source file and any functional differences are reported as an error.
.LP
There is no requirement that the upgraded file exactly match the release
file.  Thus, some scripts may add functionality to the end of the user's
file instead of installing it in same place as the release file.
.B chkclasses
attempts to recognize files which do not exactly match but are
functionally equivalent.
.LP
.B chkclasses
tests only a single architecture at a time.  The architecture
may be specified with the
.B "-a"
option.  If no arch is given, it will try to be determined by looking
in the compare tree.
.LP
The base and compare trees are assumed to be in the structure of a build
proto area.
It is not required that either tree be fully
populated but they are expected to contain the files listed in the
editable classes.  Most likely the compare tree will be a build
of the release currently being developed.  It is not practical or
necessary for the base tree to be a full build.  The script
.B mkclassproto
can be used to create a directory structure from a build area which
only contains the files found in the editable classes.
The
.B \-l
option may be used to generate a list of files in the editable classes.
.LP
The list of classes and files in those classes is built from a package
definition directory tree.
The tree is recursively searched for directories which define packages.
A package definition is assumed to be a directory with contains a pkginfo
and prototype files.
The pkginfo may be named anything as long as it starts with pkginfo.
The top prototype file must be named either prototype or prototype_<arch>.
The "!include" syntax of the prototype file is understood so that prototype
files may be nested.
The path1=path2 syntax of the prototype is supported where path1 indicates
the installed pathname (destination) and path2 indicates where the file
resides on the machine which contains the actual data (source).  In
such cases, the source path (path2) is used.
Common classes such as
.I none
and
.I renamenew
which do not merge user changes
are excluded from testing.  Additional classes may be excluded
using the
.B "-E"
option.
.LP
Class action scripts are tested for re-entrance.
If the generated file compares correctly, the script will be run again
with this file as the destination and the resulting file compared with the
compare file to ensure it is not modified a second time.
Re-entrant testing may be disabled with the
.B "-r"
option.
.LP
Class action scripts are required to preserve any users' changes.
If a file exists in the base area under the same pathname and ends in a .mod,
this is assumed to be a modified version representing a file with changes
a user might make.
It will be compared against the normal base file and the differences recorded.
The class action script will then be run with this file as the destination and
the resulting file compared to the compare file.
Any discrepancies between the two diffs will be considered an error.
Modification testing may be disabled by the
.B "-m"
option.
The .mod file will also be tested for re-entrance unless the
.B "-r"
option is
given.
Missing .mod files will be reported as a warning unless the
.B "-q"
option is specified.
.LP
When a test fails, the class, package, and pathname along with the output
of diff, are written to stdout.  The
.B "-x"
option may be used t get context diffs.
.SH OPTIONS
.TP 10
.BI \-b basedir
Root directory of the base proto tree.
.TP 10
.BI \-c cmpdir
Root directory of the compare proto tree.
.TP 10
.BI \-p pkgdir
Root directory of the package definition tree.
.TP 10
.BI \-a arch
Specify the architecture.  Different platforms of the same architecture are
translated to the base architecture.  Thus sun4, sun4c, sun4m, etc. are
translated to sparc.
.TP 10
.BI \-C class
A comma separated list of classes to test.
.TP 10
.BI \-E class
A comma separated list of classes to exclude from testing.
.TP 10
.B \-r
Disable re-entrant testing.
.TP 10
.B \-m
Disable modification (preservation of user's changes) testing.
.TP 10
.B \-x
Display context diffs.
.TP 10
.B \-k
Keep copies of files which failed a test.  Files are saved in the directory
/tmp/class.keep.<user>.
.TP 10
.B \-v
Verbose; list each class/file as it is tested.
.TP 10
.B \-l
Generate a list files found in the editable classes.
If the verbose option (-v) is specified, class and package names are included
in the listing.
.TP 10
.B \-q
Turns on quiet mode and suppresses the printing of warning messages.
.SH SEE ALSO
mkclassproto(N), chkclassproto(N), syncprotos(N)
.SH CAVEATS
.LP
The comma separated list of classes for the
.B "-C"
and
.B "-E"
options must be passed as a single argument.  Therefore, there can be
no spaces between the commas or the entire list needs to be quoted.
.LP
The algorithm for recognizing functional differences is simplistic.
All the adds/deletes of one file much exactly match the adds/deletes
of the other file.  This can cause erroneous errors to reported such
as a blank line being added to a comment.
.LP
In the ON consolidation, several of the files contained within the
editable classes are installed in the proto build area with restricted
read permissions.  It may be necessary to run chkclasses as root to
test all of the files.
.LP
The list of supported architectures is hard-coded and currently only
sparc and i386 are supported.
