LEVEL3S(8)                                                          LEVEL3S(8)



NAME
       level3s - manipulate level 3 packages (viz. build, RPM, msync, test)

SYNOPSIS
       level3s {build|level2s|list|missing|msync|sane|subsync} [items]
       level3s {rpm|cpan2rpm|restore} [tar-files]
       level3s -h | help
       level3s -V | version

DESCRIPTION
       Level3s  manages  a  simple level three configuration management struc-
       ture.  This builds on level2s(8l), which keeps products under  a  revi-
       sion  controlled  directory structure (via RCS, or the like).  To group
       level 2 products into a package level3s groups related products into  a
       "source  tar  ball"  which organizes the products into a structure that
       builds them in the correct order.

       Such a package is known by a base  name  and  a  release  number.   The
       release  number  is  usually  the revision of a key member file, or the
       ITO.spec file used to build the package.

       Using the source package produced we build  an  RPM  (see  rpm(1)),  or
       extract  the  aggregated  files  on  another  machine to use the master
       source structure to build across any number of hosts (see msrc(8l)), or
       publish the tar archive to source consumers.

       Package source directories are kept under /usr/msrc/Pkgs.  Packages are
       located by the existence of the file ITO.spec the directory.  Note  tha
       level  1  refers  to  the  file management used to revision control the
       source files, the default interface  is  assumed  to  be  rcs(1).   See
       msync(8l) for more details about the common conventions for each source
       directory, since the rules are all the same for level  2  and  level  3
       working directories.

RPM SPECIFICATION
       A  standard  RPM  specification  file called ITO.spec marks each level3
       package directory.  It is the RPM spec file and is also marked-up  with
       mk(1l) lines to provide some meta-information.

       $Level3: ${echo:-echo} package
              Outputs  the  name  of  the package directory, which is also the
              name of the package.  This is mostly a sanity  check  to  assure
              that  the  spec-file  is  in  the  correct directory (and not an
              unconfigured template).

       $KeyFile: ${echo:-echo} entry
              This marker must produce the  name  of  the  distinguished  file
              whose revision control markup provides the version number of the
              package.  When no such marked line exists  the  ITO.spec  file's
              revision information is assumed.  See ident(1), and mk(1l).

              For  example this marked comment selects README as the file with
              the correct revision number.
                   # $KeyFile: ${echo:-echo} README $$
              The double-dollar ($$) is mk markup, and is optional under  most
              site's local policy.

       $List2s: ${cat:-cat} list
              This  markup  outputs  the  list  of level 2 products.  The each
              product directory is listed in a single line, and must  be  pre-
              fixed  with either $MSRC_ROOT/ or just a leading slash (/).  The
              package name may be followed by a specific  revision  label  (to
              override  the  verof  default).   Comments  and  shell code (not
              matching those patterns) may be embedded  amongst  the  packages
              listed. For example:
                   # comment
                   $MSRC_ROOT/local/bin/oue Two
                   $MSRC_ROOT/local/bin/glob One
                   (sleep 1)
                   $MSRC_ROOT/local/bin/forever One
              This  steeam  is  converted  to  a shell script which builds the
              package.  Sources are checked out from rcs vi co(1), by default.
              So each directory should be a stable level 2 package.

              The  list  could be in an external file (as above), or presented
              as an mk(1l) here document (via mk's  %j)  inside  the  ITO.spec
              file itself.  For example:
                   # $List2s: %|/# /%J ${cat:-cat} %j
                   # # comment
                   # $MSRC_ROOT/local/bin/oue Two
                   # $MSRC_ROOT/local/bin/glob One
                   # (sleep 1)
                   # $MSRC_ROOT/local/bin/forever One
                   # $List2s: %j%^

OPTIONS
       In  each of the commands below items is either the full path to a level
       2 directory, or the name of the level2 package built.   When  none  are
       specified all level 2 packages are assumed.

       -h or help
              Output only the standard command-line usage information.

       -V or version
              Output only the standard version information.

       build [items]
              Construct  a level3 package for each requested directory, or all
              when none are specified.  Note that these all ship with a common
              file owner ($SOURCE).

       level2s [items]
              List the level2 products included in the level3 items.  The oup-
              tut format is "directory symbolic-version".

       list [items]
              Output the list of  level  3  directories  and  some  additional
              information  about each.  This table is mostly useful for debug-
              ging the program itself.

       missing [items]
              List all the missing tar  archives  for  all  the  given  items.
              (Always run this from the directory that holds such files.)

       msync [items]
              Run msync for each of the given items, and all the level 2 prod-
              ucts included.

       sane [items]
              Run an internal sanity check for each of the given items.

       subsync [items]
              Run msync for each level 2 directory under the  specified  pack-
              ages.

       These operations use the tar ball as the specification, rather than the
       master source directory:

       restore [items]
              Put the contents of the named tar files back into the local mas-
              ter source.  If you add an RCS directory and force a check-in of
              the files at the correct versions you should have  exactly  what
              the  author  had  tagged when she build the tar archives.  Reads
              the environment variable $MSRC_ROOT for the leading path to  the
              local master source cache (which defaults to /usr/msrc).

       rpm [rpm-options] tar-files
              Turn  the  source  tar  ball  into  an RPM via rpmbuild(1).  The
              optional rpm-options must be presented as words that start  with
              dash (-).

NOTES
       The  package "Example" is exempt from most operations since it is not a
       real package or product.

EXAMPLES
       level3s -V
              Output the version of level3s.

       level3s build install_base
              Build a level3 package for install_base using the definition  of
              install_base from the local master source.

       level3s rpm msrc_base-2.42.tgz
              Build  a  rpm  from  msrc_base-2.42.tgz.   The  ITO.spec  in the
              gzipped tar file is extracted  into  /usr/src/redhat/SPECS  then
              the  tarball  is placed into /usr/src/redhat/SOURCES.  Then rpm-
              build(8) -ba runs against the extracted spec  file,  and  binary
              and source rpms are built and placed in /usr/src/redhat/RPMS and
              /usr/src/redhat/SRPMS,  respectively.   As  a  side-effect   the
              binary  rpm  is installed.  (Or under /root/rpmbuild/, depending
              on the Linux distro.)

       level3s rpm '--target i686' msrc_base-2.43.tgz
              As above, but name the platform target architecture.

       level3s list msrc_base
              Outputs the path to the directory, the key file name,  the  cur-
              rent  symbolic  version,  and the name of the package with colon
              (:) separators:
              /usr/msrc/Pkgs/msrc_base:Makefile:Two:msrc_base:2.44

       level3s msync
              Run msync(8l) on the package directory as well as every included
              level2  package  in  the  product.   This depends on the list of
              level2 products specified in the ITO.spec file.

       level3s level2s |xapply -vf 'cd %[1 1] && ckmake Makefile*' 2>&1 |less
              Check all the make recipes under  every  level2  enclosed  in  a
              package.

ENVIRONMENT
       $MSRC_ROOT
              The  root  of the level2 products.  This is shared with level3s.
              By default set to "/usr/msrc".

       $MSRC_PKGS
              The root of the level3 packaging recipes.  By  default  this  is
              derived from $MSRC_ROOT/Pkgs.

       $SOURCE
              The  committer  group for the master source structure.  Defaults
              to the name "source".  Also used by level3s and msync.

BUGS
       The program is a little slow to start as it gathers the list of all the
       product directories via find(1) over /usr/msrc/Pkgs.

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

SEE ALSO
       mk(1l),   msync(8l),   rcsvg(1l),  ckmake(8l),  level2s(8l),  ident(1),
       msrc(8l), mmsrc(8l), make(1), tar(1), gzip(1), rpm(8), rpmbuild(8)



                                     LOCAL                          LEVEL3S(8)

NAME | SYNOPSIS | DESCRIPTION | RPM SPECIFICATION | OPTIONS | NOTES | EXAMPLES | ENVIRONMENT | BUGS | AUTHORS | SEE ALSO