MSYNC(8)                                                              MSYNC(8)



NAME
       msync,  verof - verify that a master source directory follows site pol-
       icy

SYNOPSIS
       msync [-3R] [-m prereq[:postreq]] [diff-opts] [version] [directory]
       msync -G [directory]
       msync -N [directory]
       msync -V
       msync -h
       verof [directory]

DESCRIPTION
       Msync checks  the  make(1)  recipe  file  in  the  specified  directory
       (default  .) against the policy invariants for a master source product.
       Any deviation from the normal rules is noted on stdout.

       There must be an msrc make recipe file in the  directory.   It  can  be
       named "Msrc.mk", "msrc.mk", or the common names, see msrc(8l).

       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 rcs(1).  Any files in the GEN make
       macro are exempt from this rule.

       No file should be missing an RCS cache under RCS, when  that  directory
       exists.

       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).   An
       exception is made for any file named "-No_rm_star", which was once com-
       monly used to prevent the accidental discard of RCS cache files.

       All plain files should be listed in the make recipe file in either  the
       SOURCE or GEN macros.

       Every  file  must  be  in sync with the symbolic version provided.  The
       default version is based on the highest revision of the recipe file.

       Every  working  file  must  be  in  the  $MSYNC_GROUP  group   (default
       "source").   If  there  is an mk(1l) marked line (in the control recipe
       file) that matches "Msync(group)"  then  the  output  of  that  command
       should be the name of the group for this directory.

       No RCS cache file name should start with a leading dot (.).  It is typ-
       ical to replace a leading dot with the letter x (or X).

OPTIONS
       If the program is called "verof" the -N option is forced.

       The diff-opts allowed are -b, -c, -i, -w,  -ulines,  -Ulines,  -Clines,
       see diff(1).

       -h
              Output the standard command-line usage information.

       -m prereq[:postreq]
              This  specification is processed just as msrc does.  It provides
              the provision recipe and (optionally) a  cleanup  recipe.   Note
              that  just  as  in  msrc  the cleanup recipe could actually be a
              white-space separated list.

       -G
              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
              Msync(group),  see  mk(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 descen-
              dant directories.

       -N
              Output the expected symbolic version for each directory.

       -R
              Under this option msync checks and explicit elements of the make
              macro SUBDIR for consistency with the target directory.

       -V
              Output the standard version information.

       -3
              Assume  that  the  directory is a level3 package directory, even
              without the "Makefile.meta" file.  This sets a fake  INTO  macro
              as in the example below.

PROCESS
       Msync  locates the controlling recipe, extracts markup and marco infor-
       mation 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 Distfile or a file  named  Make.host),  because
       they have different rules.

       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.

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

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

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

       Otherwise we check the macros in the control recipe against  the  files
       in  the  directory.   The recipe must render a SOURCE macro, and should
       render GEN, and SEND.  Then each directory listed in SUBDIR is checked,
       under -R.

EXAMPLES
       msync
              Commonly  used after a commit to the local revision control sys-
              tem to verify that the change didn't corrupt the build system.

       msync Two
              See if the current directory is stable a  the  symbolic  release
              Two.

       msync -- -- */
              See  if  all  the  directories under the current are at the same
              revision.

       msync \$ *
              Use rcsdiff(1) to check each file against the version  given  in
              its rcs keywords.  See co(1).

       msync -N
              Report  only  the  symbolic name local policy would use for this
              directory.

       MYTMP='mktemp -d /tmp/${USER}XXXXXX'
       MSRC="-y INTO=$MYTMP" msync
              Force a layer 3 package directory to skip  the  failure  message
              that  it is not buildable via msrc.  Remember to remove the junk
              directory, specified in $MYTMP, when you are done.

       msync -3
              Do almost exactly what the previous example does,  only  better.
              This version of the level3 check doesn't overwrite $MSRC.

       make msync
              If  the  msync  command requires fixes like the example above it
              may be better form to put the command in the control recipe.   I
              would.

       msync -u2 -w
              Report  differences  in  unified  format  and ignore white-space
              changes.

       rcsdiff -q -r\$ RCS/*,v
              If msync doesn't work because of an issue with the recipe  file,
              then this is the next-best check command.  Replace the \$ with a
              symbolic revision name to check a specific tag.

BUGS
       Since msync gets the control recipe from head revision in the  revision
       control  system  updates  made  to  the  current  edit  of the file are
       ignored.  You must 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.)

       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 "OrgSync".

       BSD has an obsolete system call by the same name.

       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.

       If msrc is not installed the program falls back to BSD make's -V option
       to  recover the required macro values, but that is really not portable.
       It is possible to use GNU gmake's -p option to find a variables  value,
       but the output is hard to parse and ambiguous.

ENVIRONMENT
       $MSYNC_GROUP
              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 system.  When provided by mk markup
              in any directory, the new value  becomes  the  default  for  any
              recursive instances.

       $MSYNC_SYMBOLIC
              When  running  a  locally  selected recipe to check a directory,
              this environment variable holds the expected  symbilic  revision
              name.

       $VersionFunc
              Is  taken  as the name of the program that filters revision num-
              bers into  the  expected  symbolic  name.   The  default  in  an
              internal  function that maps the numbers 1 to 20 to English word
              "One", "Two", ...  "Twenty".

       $MSRC
              Read by msrc for additional command-line options.

       $MSYNC_CHECK
              If unset or set to "true" msync looks for the marker  Msync(tar-
              get)  in  the control recipe.  The output of that command should
              be a list of make targets to update to output the status of  the
              directory.   Recursive  calls  to  msync  are  allowed.   In any
              descendant process the variable is set  to  "false"  to  prevent
              infinite  recursion.  Set this to any command that exits with an
              apropos code (viz. 0) for "try the recipe targets" on stdout, or
              non-zero for "use the internal checks".

              This  is  mostly used to trap level 1 and level 3 products which
              are kept under /usr/msrc for historical reasons.

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

REFERENCES
       The completely unrelated msync(2), the HTML description in  the  source
       to this program.

SEE ALSO
       diff(1),  msrc(8l),  mmsrc(8l), mk(1l), oue(1l), rcsvg(1l), tickle(8l),
       make(1) or gmake(1)



                                     LOCAL                            MSYNC(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | PROCESS | EXAMPLES | BUGS | ENVIRONMENT | AUTHORS | REFERENCES | SEE ALSO