.\" $Id: level2s.man,v 4.16 2012/07/06 21:04:37 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/level2s.8
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]8/level2s.8*
.TH LEVEL2S 8L LOCAL
.SH NAME
level2s \- manipulate level2 packages (viz. build, RPM, msync, test)
.SH SYNOPSIS
.ds PN "level2s
\fI\*(PN\fP {\fBbuild\fP|\fBlist\fP|\fBmissing\fP|\fBmsync\fP|\fBrestore\fP|\fBsane\fP} [\fIitems\fP]
.br
\fI\*(PN\fP {\fBrpm\fP|\fBcpan2rpm\fP} [\fItar-files\fP]
.br
\fI\*(PN\fP \fB\-h\fP | \fBhelp\fP
.br
\fI\*(PN\fP \fB\-V\fP | \fBversion\fP

.SH DESCRIPTION
\fILevel2s\fP manages a simple level two configuration management structure.
It builds on level 1 where we keep each file under a revision
control structure (like RCS, or CVS).  At level 2 we packages related
files into a "source tar ball" that holds a product at a particular version.
The version is usually the revision name of a key member file.
.P
Using that source package we may build an RPM (see \fBrpm\fP(1)), or
extract the aggregated files on another machine to
use the master source structure to build across many hosts or a single host
(see \fBmsrc\fP(8l)), or publish the tar archive for source consumers.
.P
The source directories for each level2 product are kept under
\fB/usr/msrc/\fP and are located by the existence of the file \fBITO.spec\fP
in each source directory.  See \fBmsync\fP(8l) for more details about
the common conventions for each source directory.

.SH "ITO.SPEC"
A standard RPM specification file called \fBITO.spec\fP marks each
level2 source directory.  It is the RPM spec file and is also
marked-up with \fBmk\fP(1l) lines to provide some meta-information.
.TP
\fB$KeyFile:\fP
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 \fBITO.spec\fP file's revision information
is assumed.  See \fBident\fP(1), and \fBmk\fP(1l).
.sp
For example this marker selects the "README" file as the file with
the correct revision number.
.nf
	$\&KeyFile: ${echo:-echo} README $\&$
.fi
.TP
\fB$Level2:\fP
This should return the package name, if it is not the last component name of
the directory.
.TP
\fB$Level3:\fP
If this succeeds, it outputs the name of the level3 package that
includes this product (so we don't build a stand-alone package for it).

.SH OPTIONS
In each of the commands below \fIitems\fP is either the full path
to a level2 directory, or the name of the level2 package built.
When none are specified all level2 packages are assumed.
.TP
\fB\-h\fP or \fBhelp\fP
Output only the standard command-line usage information.
.TP
\fB\-V\fP or \fBversion\fP
Output only the standard version information.
.TP
\fBlist\fP [\fIitems\fP]
Output the list of directories and some additional information about
each.  This table is mostly useful for debugging the program itself.
.TP
\fBbuild\fP [\fIitems\fP]
Construct a level2 package for each requested directory, or all when
none are specified.
.TP
\fBmissing\fP [\fIitems\fP]
List all the missing tar balls for all the given \fIitems\fP.
.TP
\fBmsync\fP [\fIitems\fP]
Run \fBmsync\fP for each of the given \fIitems\fP.
.TP
\fBrestore\fP [\fIitems\fP]
Put the contents of the named tar files back into the local master source.
If you add an RCS directory and force a checkin 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 $\fBMSRC_ROOT\fP
for the leading path to
the local master source cache (which defaults to \fB/usr/msrc\fP).
.TP
\fBsane\fP [\fIitems\fP]
Run an internal sanity check for each of the given \fIitems\fP.
.P
These operations use the tar ball as the specification, rather than
the master source directory:
.TP
\fBrpm\fP \fItar-files\fP
Turn the source tar ball into an RPM via rpmbuild(1).
.TP
\fBcpan2rpm\fP \fItar-files\fP
Turn a CPAN tar ball into an RPM using local site policy for the
location and \fBhxmd\fP's \fBauto.cf\fP for the \fBmmsrc\fP
configuration.

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

.SH EXAMPLES
.TP
.nf
\fI\*(PN\fP \-V
.fi
Output the version of \fBlevel2s\fP.
.TP
.nf
\fI\*(PN\fP build unixstats
.fi
Build a level2 package for unixstats using the definition of unixstats from
the master source.
.TP
.nf
\fI\*(PN\fP rpm unixstats-1.0.tgz
.fi
Build a rpm from unixstats-1.0.tgz.  The ITO.spec in the .tgz is extracted
into /usr/src/redhat/SPECS and the tarball is placed into
/usr/src/redhat/SOURCES.  \fBrpmbuild(8) \-ba\fP will then run against the
extracted .spec file, and binary and 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.
.TP
.nf
\fI\*(PN\fP cpan2rpm /tmp/My-Favorite-Cpan-Package-1.0_4.tar.gz
.fi
Build a rpm from My-Favorite-Cpan-Package-1.0_4.tar.gz. A .spec file will be
auto-magically generated from the .tar.gz.  Attempts are made to extract summary
and description from embedded documentation in the tarball.  If said
documentation is absent, building will fail.  Source and binary rpms are built
into the same locations as above.  The binary rpm is installed.
.TP
.nf
\fI\*(PN\fP list Tee
.fi
Outputs the path to the directory, the key file name, the current symbolic
version, and the name of the package with colon (\fB:\fP) separators:
.RS
/usr/msrc/usr/local/bin/Tee:Tee.m:Two:Tee
.RE
.TP
.nf
\fI\*(PN\fP restore efmd-*.tgz
.fi
Reconstruct the master source (as best we can) for \fBefmd\fP from
the compressed distribution source \fBtar\fP archive.  The revision
history is lost, since it is not included in the source package.
And local changes should be kept under the local site policy for
revision control.

.SH ENVIRONMENT
.TP
$SOURCE
The committer group for the master source structure.  Defaults to the
name \*(lqsource\*(rq.

.SH BUGS
The program is a little slow to start as it gathers the list of
all the product directories via \fBfind\fP(1) over \fB/usr/msrc/\fP.

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

.SH "SEE ALSO"
.hlm 0
mk(1l), msync(8l), rcsvg(1l), ident(1), msrc(8l), mmsrc(8l), tar(1), gzip(1),
rpm(1), rpmbuild(8), level3s(8l)