README for atelerix
===================
Atelerix simplifies building an RPM directly from a version control system.
It is a Makefile (named atelerix.mk), which you can include in your Makefile
and can be used for RPM-packaging just about anything (shell scripts, Python,
Perl, C, Java, and more). One useful feature is its ability to drive package
building directly from tags in a version control system (git, svn, hg). 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 your Makefile.
You should know the basics of an RPM specfile. Learn how to write the
%files section at absolute least.
Your Makefile needs only to 'include /usr/lib/atelerix/atelerix.mk'.
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. source control management (SCM).
The specfile.in describes the files belonging to the RPM.
The Makefile 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, rm, mv, gzip, tar, ln,
rmdir, id)
* rpm (rpm, rpmspec, rpmbuild); should work with any rpm-4.x or newer
* one of these source control programs:
- git > 1.5.x; uses 'git-archive'
- svn
- hg
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, OBS integration work.
* Greg Ward; corrections and many improvements to Makefile-fu.
* Eric Estabrooks; rpmspec fixes and mercurial beginnings.
* Many suggestions, minor fixes and one-liners from others, including Clint
Hepner, Paul Felix, David Schein, Stephen Ryan and Rob Bushell.
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.
Consult your local intellectual property guru for advice.
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
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.