[editor's note: the author of this software is
 Michael Beach <mbeach@awa.com.au> ]


INTRODUCTION

This is a first attempt at documentation for the CVS to RPM conversion
program (it's so new, it doesn't even have a name yet!). Apart from
the source code itself, this file is the definitive documentation. The
large block comments in the source code may be of some use, but
reflect more my thoughts as I was hacking together the program, rather
than its finished state.


WHAT IS IT MEANT TO DO?

It is meant to make it easier to generate source and binary rpms fit
for distribution (ie not ugly unreadable abominations) from source
archives held under CVS. It will create tarballs, patch files and a
spec file in nominated locations, typically those will be the same
locations that RPM uses. It is then simply a case of issuing rpm -ba
against the generated spec file in order to build binary and source
RPMs.

It allows for the generation of RPMs by other than the original author
of the program being packaged, through the use of CVSs vendor branch
mechanism. If desired, a tarball will be generated for the vendor
branch (the pristine sources) and a patchfile which includes all local
(packager introduced) changes.

It is also intended to allow reproducibility; at any later time it
should be possible to rebuild an RPM from the repository. Of course
this is only possible as far as the configuration of the build machine
permits.


HOW DOES IT DO IT?

Essentially the program is a macro-mangling engine that knows how to
invoke CVS and tar. It relies upon the CVS tags used to label the
sources to be incorporated in the RPM to contain the relevant version
information. It extracts this using regular expressions and then
allows it to be substituted into the names of the tarballs and the
directories within them, and into the template spec file and its
name. Along the way if invokes CVS and tar to build the tarballs and
patch files.


HOW DO I USE IT?

In order to use this program, you will need to have sources under CVS
that you want to package with RPM. You will also need for each source
RPM (ie for each spec file) you intend to create, a description file
and a release file. The description file contains information about
what CVS modules are used in the RPM, how to extract version
information from the tags used in these CVS modules, how to name the
patch files and the tarballs and the directories within the tarballs,
and of course a template spec file. The description file is itself
kept under CVS, so that changes in the RPM's meta information (spec
file contents, file names etc) can be maintained. The release file is
used to describe each RPM generated. It specifies the tags to be used
for extracting the source for each CVS module, which description file
to be used (including version number) and the release number to be
used.

Both the description file and the release file consist of
s-expressions. For non Lisp-heads this simply means that clauses in
these files are delimited by an opening and a closing parenthesis. It
also means that you can use Emacs to do cute indenting automatically.

Example description and release files are included, named kernel.descr
and rpmrel respectively. These are files I use for building RPMs for
the Linux kernel from a CVS repository.

The description file should contain the three s-expressions given
following. No particular order is required, but the order given below
seems to make sense.

(srpm-name "name of the spec file")

This defines the name of the spec file to be generated. The string
will typically contain macros that will be expanded.

(cvs-modules ...)

This s-expression will contain a sequence of other s-expressions, each
of which describes one of the CVS modules which contributes to the
RPM. Each of these s-expressions, in turn, is a sequence of the
following types of s-expression.

(name "shorthand name for CVS module")

This gives an arbitrary name to the CVS module. It should be unique
among the CVS modules used in this RPM. It is how CVS modules are
referred to in macros.

(cvs-name "cvs/module/name")

This is the name under which to find the module in the CVS repository.

(tag-to-version-id-re "regexp" "subst string")

This s-expression specifies how to generate a version identifier from
the CVS tag used to identify the source version in the repository. The
regexp matches the CVS tag, and is one of the 'Henry Spencer' style
regexps that most packages seem to use. Parenthesised expressions in
the regexp are captured and numbered from 1 upwards (0 is the string
matched by the entire regexp). Then every occurrence of @n in the
subst string is replaced with parenthesised expression n from the
regexp. The value resulting from this substitution is then available
as the version-id macro for this CVS module.

(tag-to-patch-id-re "regexp" "subst string")

Similar to the tag-to-version-id-re s-expression described above, this
one generates a macro called patch-id from the CVS tag used to
identify the local changes to sources. This is only of significance if
the sources under CVS are from a 3rd party, and the CVS vendor branch
mechanism is used.

(tarball-name "name")
(dir-name "name")
(patch-name "name")

These describe the names to be used when the tarball (and optionally
patchfile) for the module are to be generated. tarball-name gives the
actual name for the tar file, dir-name gives the name for the top
level directory in the tarball (the name from the CVS module may not
be what you want) and the patch-name gives the name of the patch file
to be generated (if required). Each of the strings will typically
contain macros to be substituted, usually either the version-id or the
patch-id. The format for such macros is @{macro-name}, eg
@{version-id} or @{patch-id}.

After the (cvs-modules ...) s-expression, comes the
(spec-file-template ...) s-expression. What comes after the
spec-file-template keyword is simply a string which contains the spec
file template. However, to avoid hairy quoting hassles, it is easiest
to use a scsh feature called a here string, rather than using
"...". This works just like a Bourne shell style here document, just
start it with #<<end-token, and terminate it again with end-token.

This string should contain an entire spec file template, and will
typically use many macros so that the template is insensititive to the
version of software you are building the RPM of. Macros are specified
similarly to before except that there are multiple CVS modules
contributing to the RPM, so some means is required to tell whether you
are referring say to the version-id of one CVS module or another. This
is done using a macro syntax of @{name:macro}, where name is the
shorthand name given to the CVS module in the (cvs-modules ...)
s-expression. The only exception to this is @{rel-num}, which refers
to the release number of the RPM, and is not associated with any
particular CVS module. The macros that can be substituted are not
limited to version-id and patch-id. tarball-name, dir-name and
patch-name may also be used.

The release file also consists of a series of s-expressions. Each of
these is a release record, and has the following format:

(rel-id rel-num "descr/file/CVS/name" "descr file CVS version"
	("module name" "CVS tag" "optional CVS tag")
	...)

rel-id is a unique integer identifying this release record, rel-num is
the integer release number for the RPM, "descr/file/CVS/name" is the
name of the description file in the CVS repository, and "descr file
CVS version" is its version number. Following this is a series of
s-expressions, one for each of the CVS modules contributing to the
RPM. Each of these consists of the shorthand name for the CVS module
as given in the description file, followed by a CVS tag for that
module, followed optionally by another. If both tags are present, the
first represents the version on the vendor branch, and the second
local modifications. Patch files are generated using the difference
between the sources tagged by the first and second tags.

Ok, so once you have the sources under CVS, have your description file
under CVS, and have a release file with the appropriate entry in it,
you are almost ready to go. The only thing you may wish to do is
customise some of the paths used in the program. They are given by the
last 3 (define ...) forms in the source code. *scratch-dir* is used as
a scratch area for directory trees to be built into tar
files. *rpm-spec-dir* and *rpm-source-dir* are where the spec file and
sources are placed respectively.

Next, invoke the program as

./srpm-build.scm rel-file rel-id

where rel-file is the name of the release file and rel-id is the
identifying number of the release record in that file for which you
wish to do the build. This should grab the required sources from CVS
and stick them in the *rpm-source-dir* and generate a spec file and
place it in *rpm-spec-dir*.

There are several optional switches that can be given. These are

--no-clean

Don't tidy up the scratch directory, leave the directories used to
make the tarballs lying around afterwards. This is handy if you later
want to use one of the other two flags.

--no-source
--no-cvs

These flags are used to short circuit some of the tarball and patch
creation. This is handy if you are just fiddling about getting the
spec file right, as CVS exports acn take up a bit of time on large
modules (eg the Linux kernel sources). The --no-source flag will cause
nothing to be created in the *rpm-source-dir*, while the --no-cvs flag
just short circuits the cvs export, and the tarballs will be built
from whatever is in the scratch directory (assumes --no-clean has been
used sometime previously).

The program can also be used interactively from the scsh prompt, to do
this just load it at the prompt. The top level function is called
entry-point; figure it out from there.


CAVEATS

-p flag for patching.

Because the patch files are generated by CVS, the names given for the
files in the patch hunks are given relative to the CVS repository. If
the module is nested several directories deep in the repository, then
it may be necessary to use the -p flag to ensure that these
directories are stripped off when applying the patch.

Sources must live in a tarball.

The program as it stands assumes that everything must either be a
source tarball or a patch file. Single source files are not on. If you
have such source files, they're going to have to be placed inside a
tar file.


TODO

Not necessarily in order of importance...

Tidy up sources.
Improve error handling.
Move to a Scheme implementation which is not such a sloth (RScheme ?).
Fix up infelicities in macro substitution.
Externalise all config information.