.\" $Id: msync.man,v 4.34 2012/09/05 23:34:27 ksb Exp $
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man8/msync.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/msync.8*
.TH MSYNC 8 LOCAL
.SH NAME
msync, verof - verify that a master source directory follows site policy
.SH SYNOPSIS
.ds PN "msync
.ds PA "verof
\fI\*(PN\fP [\fB\-3R\fP] [\fB\-m\fP\~\fIprereq\fP[:\fIpostreq\fP]] [\fIdiff-opts\fP] [\fIversion\fP] [\fIdirectory\fP]
.br
\fI\*(PN\fP \fB\-G\fP [\fIdirectory\fP]
.br
\fI\*(PN\fP \fB\-N\fP [\fIdirectory\fP]
.br
\fI\*(PN\fP \fB\-V\fP
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PA\fP [\fIdirectory\fP]

.SH DESCRIPTION
.I Msync
checks the \fBmake\fP(1) recipe file in the specified \fIdirectory\fP
(default .) against the policy invariants for a master source product.
Any deviation from the normal rules is noted on \fIstdout\fP.

.P
There must be an \fBmsrc\fP \fBmake\fP recipe file in the \fIdirectory\fP.
It can be named "Msrc.mk", "msrc.mk", or the common names, see \fBmsrc\fP(8l).
.P
All plain files must be checked into RCS, or CVS so there must be either
a RCS or CVS subdirectory.  All files should be read-only, as they
should be unlocked according to \fBrcs\fP.
Any files in the \fBGEN\fP \fBmake\fP macro are exempt from this rule.
.P
No file should be missing an RCS cache under RCS, when that directory exists.
.P
No unrelated files in any RCS or CVS subdirectory (viz. those that don't end in ``,v'', or are not part of CVS's known working files).
.P
All plain files should be listed in the \fBmake\fP recipe file in either the
\fBSOURCE\fP or \fBGEN\fP macros.
.P
Every file must be in sync with the symbolic \fIversion\fP provided.
The default \fIversion\fP is the highest revision of the recipe file.
.P
Every working file must be in the $MSYNC_GROUP group (default "source").
If there is an \fBmk\fP(1l) marked line that matches \*(lqMsync(group)\*(rq
then the output of that command should be the name of the group for this
directory.

.SH OPTIONS
If the program is called \*(lq\*(PQ\*(rq the \fB\-N\fP option is forced.
.P
The \fIdiff-opts\fP allowed are \fB\-b\fP, \fB\-c\fP, \fB\-i\fP, \fB\-w\fP,
\fB\-u\fP\fIlines\fP, \fB\-U\fP\fIlines\fP, \fB\-C\fP\fIlines\fP,
see \fBdiff\fP(1).
.TP
.nf
\fB\-h\fP
.fi
Output the standard command-line usage information.
.TP
.nf
\fB\-m\fP \fIprereq\fP[\fB:\fP\fIpostreq\fP]
.fi
This specification is processed just as \fBmsrc\fP does.
It provides the provision recipe and (optionally) a cleanup
recipe.  Note that just as in \fBmsrc\fP the cleanup recipe
could actually be a white-space separated list.
.TP
.nf
\fB\-G\fP
.fi
Output the expected group ownership for every source file.  This
is taken from the environment variable $MSYNC_GROUP, or a marked command
in the control recipe file.  The marker specified is \fBMsync(group)\fP,
see \fBmk\fP(1l).  When neither one is available, the default is "source".
The marked command output is preferred to the variable, which is set
to the forced group for any descendant directories.
.TP
.nf
\fB\-N\fP
.fi
Output the expected symbolic version for each \fIdirectory\fP.
.TP
.nf
\fB\-R\fP
.fi
Under this option \fI\*(PN\fP checks and explicit elements of the
\fBmake\fP macro \fBSUBDIR\fP for consistency with the target directory.
.TP
.nf
\fB\-V\fP
.fi
Output the standard version information.
.TP
.nf
\fB\-3\fP
.fi
Assume that the directory is a level3 package directory, even without
the \*(lqMakefile.meta\*(rq file.  This sets a fake \fBINTO\fP macro
as in the example below.

.SH PROCESS

\fIMsync\fP locates the controlling recipe, extracts markup and
marco information from that file (actually the most recent version in
the revision control cache).  Then it checks for older versions of
the master source structure (a file named \fBDistfile\fP or a file
named \fBMake.host\fP), because they have different rules.

.P
It maps the numeric version of that recipe file to a symbolic name.
That symbolic name is used to check that every file's revision cache
is synchronized is the current working file.

.P
Then it looks for any \fBtarget\fP markup, if there is any it
gives control to \fImake\fP with the specified targets, no recursion
is attempted and the rest of the arguments are ignored.

.P
Otherwise it deduces the control group and updates the environment
with the new group name.

.P
Under \fB\-V\fP we output all the information we've gathered with
our version information and exit.

.P
Otherwise we check modes and revisions of the current files against the
known modes and symbolic version tags.  If the \fB\-G\fP option
is set then we are done, and output only the group (we do check
other listed directories to be sure they match our group).

.P
Otherwise we check the macros in the control recipe against the
files in the directory.  The recipe must render a \fBSOURCE\fP
macro, and should render \fBGEN\fP, and \fBSEND\fP.  Then each directory
listed in \fBSUBDIR\fP is checked, under \fB-R\fP.

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP
.fi
Commonly used after a commit to the local revision control system to
verify that the change didn't corrupt the build system.
.TP
.nf
\fI\*(PN\fP Two
.fi
See if the current directory is stable a the symbolic release \fBTwo\fP.
.TP
.nf
\fI\*(PN\fP \-\- \-\- */
.fi
See if all the directories under the current are at the same revision.
.TP
.nf
\fI\*(PN\fP \e$ */
.fi
Use \fBrcsdiff\fP(1) to check each file against the version given in
its rcs keywords.  See \fBco\fP(1).
.TP
.nf
\fI\*(PN\fP \-N
.fi
Report only the symbolic name local policy would use for this directory.
.P
.nf
MYTMP=`mktemp \-d /tmp/${USER}XXXXXX`
MSRC="\-y INTO=$MYTMP" \fI\*(PN\fP
.fi
.RS
Force a layer 3 package directory to skip the failure message that it
is not buildable via \fBmsrc\fP.  Remember to remove the junk directory,
specified in \fB$MYTMP\fP, when you are done.
.RE
.TP
.nf
\fI\*(PN\fP \-3
.fi
Do almost exactly what the previous example does, only better.  This
version of the level3 check doesn't overwrite $\fBMSRC\fP.
.TP
.nf
make \*(PN
.ni
If the \fI\*(PN\fP command requires fixes like the example above it may
be better form to put the command in the control recipe.  I would.
.TP
.nf
\fI\*(PN\fP \-u2 \-w
.fi
Report differences in unified format and ignore white-space changes.

.SH BUGS
Since \fI\*(PN\fP gets the control recipe from \fBhead revision\fP in
the revision control system updates made to the current edit of
the file are ignored.  You \fBmust\fP checkin all your changes to
get a valid output.  This is not really a bug in the program, it is
a bug in the way most people want to work.  (Commit and test smaller changes.)
.P
This encodes ksb's local site policy by default.  Every site that doesn't
use RCS (see rcs(1)) and such must build their own version of
a tool like this.  Be warned that the code for this program may revert
when you upgrade my tool-chains.  (So you might want to name yours
something like "\fIOrg\fPSync".
.P
BSD has an obsolete system call by the same name.
.P
If you never use any revision branch other than ``One'' this program
is of less use.  You should really fix that.  Major numbers change
when you break backwards compatibility.
.P
If \fBmsrc\fP is not installed the program falls back to \fBmake\fP's
\fB-V\fP option to recover the required macro values, but is not
any more portable.

.SH ENVIRONMENT
.TP
.nf
$MSYNC_GROUP
.fi
Is taken as the name of the group that should own all source files by
site policy.  The default name "source" has
no special meaning under any known UNIX\*(TM system.
When provided by \fBmk\fP markup in any directory, the new value
becomes the default for any recursive instances.

.TP
.nf
$VersionFunc
.fi
Is taken as the name of the program that filters revision numbers into
the expected symbolic name.  The default in an internal function that
maps the numbers 1 to 20 to English word \*(lqOne\*(rq, \*(lqTwo\*(rq, ...
\*(lqTwenty\*(rq.

.TP
.nf
$MSRC
.fi
Read by \fBmsrc\fP for additional command-line options.

.TP
.nf
$MSYNC_CHECK
.fi
If unset or set to "true" \fI\*(PN\fP looks for the marker
\fBMsync(target)\fP in the control recipe.  The output of that
command should be a list of \fBmake\fP targets to update to
output the status of the directory.  Recursive calls to
\fI\*(PN\fP are allowed.  In any descendant process the variable is set to
\*(lqfalse\*(rq to prevent infinite recursion.  Set this to
any command that exits with an apropos code (viz. 0) for
\*(lqtry the recipe targets\*(rq on \fIstdout\fP, or non-zero for
\*(lquse the internal checks\*(rq.
.sp
This is mostly used to trap level 1 and level 3 products which are
kept under \fB/usr/msrc\fP for historical reasons.

.SH AUTHORS
KS Braunsdorf, Non-Player Character's Guild,
.br
msync no-spam-allowed-at ksb.npcguild.org

.SH "DOCUMENTS"
The completely unrelated \fBmsync\fP(2), the HTML description in the
source to this program.

.SH "SEE ALSO"
diff(1), msrc(8l), mmsrc(8l), make(1), mk(1l), oue(1l), rcsvg(1l), tickle(8l)