README for atelerix
===================
Atelerix simplifies building an RPM directly from a version control system.
It is most useful when the contents are mostly scripts (or other non-compiled
content).  One useful feature is its ability to drive package building
directly from tags in a version control system (git, svn, cvs).  It is relased
under the BSD license.


Example workflow
================
In this example workflow, we'll make a new package called frobnitz.

  cp -ra atelerix frobnitz
  cd frobnitz
  vim specfile.in         # -- change   Name:  frobnitz
  make test-rpm

There is now a package called ./dist/frobnitz-$VERSION-1.noarch.rpm.



What should I already know
==========================
You should have a basic understanding of a Makefile.  You will put your own
"build" and "install" commands in the Makefile.build.  This puts your software
into a temporary directory similar to where it will live in the package.

You should know the basics of an RPM specfile.  Learn how to write the 
%files section at absolute least.



How does it work
================
The Makefile has all of the logic for creating the package and interacting
with the version control system (VCS, a.k.a. SCM in this text).

The specfile.in describes the RPM.

The Makefile.build has the rules for putting the files into the correct
locations (in a buildroot/DESTDIR).





Required software
=================
  * make (tested with GNU make)
  * python (almost anything >= 1.5.2)
  * the usal suite of coreutils (mkdir, install, rpm, rpm-build, rm, mv,
    gzip, tar, ln, rmdir)
  * a source control program: 
      - git > 1.5.x; uses 'git-archive'
      - svn
      - cvs


Thanks
======
This technique for integrating package management and a version control system
developed organically out of the experience of several different people using
a variety of scripts in different environments.  Thanks are due to:

  * Renesys Corporation; where this was finally nurtured and assembled
  * Jon Nelson; ideas from prior experience

Unnamed contributors abound.


Question and answer
===================
Q: Where do I set the name of the software (package)?
Q: Where do I set the version of the software (package)?
A: In the specfile.in, there are two entries at the very top of the file.
   These are used for the name of the package and the version.  The Makefile
   uses rpm --specfile to fetch the name and version of the package for the
   build process.  The name and version are stored only in these files.  (Note
   though, that the $(NAME)-$(VERSION) are used as the tag for the version
   control system. See below for more details.)

Q: Under what license is atelerix released?
A: The BSDL.  

Q: Why does the specfile.in say "License: empty", then?
A: The example 'specfile.in' contains the rather unusual value 'empty' for
   the License field.  This is merely to emphasize that any software using the
   atelerix Makefile (and tools) should specify its own license in this field.

Q: How do I add a simple file?  For example, suppose I want to add a script
   that should end up in /usr/bin/frobnitz.
A: This involves several steps (continuing from above frobnitz example
   workflow).

     1. add the file to the directory (and your VCS)
     2. add the file to the %files specfile listing
          %attr(755, root, root) @BINDIR@/frobnitz
     3. add a section to the 'install' target of Makefile.build
          mkdir -p $(DESTDIR)$(BINDIR)
          install -m 0755 frobnitz $(DESTDIR)$(BINDIR)
     4. run "make test-rpm"

   You should get a package in the ./dist/ directory.  Check the built package
   to see if the file is in the correct place:

     5. rpm -qlp dist/frobnitz-$VERSION-1.noarch.rpm

   Look for the output showing the package with /usr/bin/frobnitz.