<!-- To convert to html: pandoc -o foo.html README.AAA_FIRST -->

Overview
========

This is rpmgrill, a set of analysis tests that run against a
particular RPM build. It principally differs from
[rpmlint](https://fedoraproject.org/wiki/Common_Rpmlint_issues)
in that rpmgrill handles *builds*, that is, the entire set of
RPMs built from one source RPM.

For example, rpmgrill can warn about missing man pages; "make" errors
or warnings buried in the build logs; or common spec file mistakes.
rpmgrill does not know about baselines or previous builds; it does
no comparisons, only isolated analysis of one build.

Terminology
===========

A **build** refers to a collection of RPMs built from a single
source RPM (which is included in the build). For purposes of
this document, builds are assumed to be generated by
[koji](http://koji.fedoraproject.org/koji/).

Context
=======

Input: one fully-unpacked koji build; see README.unpacking

Output: Three data files, same thing in different formats:

    rpmgrill.json
    rpmgrill.xml
    rpmgrill.yaml

These files contain standard information describing the build
being tested (N-V-R, data analyzed, version of the tools) and
zero or more reports from failing tests.

Invoking
========

The simplest way to start, for a given package NVR, is:

    $ NVR=coreutils-8.15-10.fc17
    $ ./bin/rpmgrill-fetch-build  $NVR my-$NVR
    $ perl -C63 -I$(pwd)/lib ./bin/rpmgrill my-$NVR
    $ vim my-$NVR/rpmgrill.yaml      (or json or xml, if you prefer)

rpmgrill runs silently, although there may be occasional output
to stdout or stderr during development of tests. These messages are
not preserved anywhere; they are intended for development and for
detecting rare problems. For more visibility, do:

    $ RPMGRILL_DEBUG=all perl .....

See `lib/RPM/Grill/dprintf.pm` for a description of this envariable.

Developing
==========

To add, extend, or fix individual rpmgrill tests see README.devel-tests

For deeper development, such as ongoing maintenance or infrastructure
development (or perhaps infrastructure bug fixes), see README.devel-deep