meta-translator
===============

Overview
---

meta-translator extends the oe-core archiver and package_rpm classes to produce
source RPM (src.rpm) packages with build commands, so that they can be rebuild
natively without the need for bitbake (i.e. on the target, or in a build system
such as OBS).

Usage
---

To use the archiver, the following variables need to be set:

# Enable the archiver, or src.rpm generation is not possible
INHERIT += "archiver"

# Archive the original sources, not patched or configured
ARCHIVER_MODE[src] = "original"

# Switch archiver mode to SRPM
ARCHIVER_MODE[srpm] = "1"

# Do not allow empty packages to be built (.rpm or .src.rpm)
# This will prevent bitbake from making a bootable image however, due to
# missing packagegroup* meta packages (which are empty)
SRPM_ALLOW_EMPTY = "1"


To generate the source RPMs for a recipe and all of the dependencies, use the
"translator" task:

$ bitbake core-image-sato -c translator

To generate the source RPMs for a specific recipe and not the dependencies, use
the "deploy_archives" task:

$ bitbake m4 -c deploy_archives

(the translator task is a simple wrapper around deploy_archives that adds
dependency recursion)

The final .src.rpm files will be found in tmp/deploy/sources, and .spec files in
tmp/deploy/rpm/specs.


Technical Overview
---

At the highest level, meta-translator is essentially a forked source archiver
class (archiver.bbclass) which calls out to a SRPM package class (forked from
package_rpm.bbclass)

The archiver is responsible for collecting all of the source files that are used
to build a recipe by invoking the 'fetch' task.  It then calls package_srpm to
write a spec file and generate a SRPM.  Whereas in normal usage package_rpm is
used to generate a minimal .spec that can build a binary package,
meta-translator generates a more complex .spec that includes the build
instructions from the .bb input so that the generated SRPM can be rebuild in
another build system (for example, OBS).

There are several complications.  Package file lists in BitBake are loose, in
that files listed don't have to exist and so the default value (set in
bitbake.conf) includes many files that are not found in an arbitrarily chosen
package.  By contract RPM file lists are strict, if a file in the list isn't
found then an error is produced.  We work around this by requiring that recipes
intended for translation need to specify exact file lists through the FILES_
variables in either the recipe or a .bbappend.

BitBake dynamically generates shell scripts that are not intended for human
consumption, so these have many exports and numerous shell functions.  Inserting
them directly into the .spec isn't feasible so key functions are replaced with
the relevant RPM macro (%configure, %make, etc) and blacklists are used to stop
exported selected variables.


To Do
---

* Implement a spec abstraction for clearer code and convenience for fixup hooks.
* Implement SMACK manifest support in a fixup hook.
* "Unwrap" shell functions when outputting the build tasks so the generated
  functions are cleaner.
* Add missing tags (BuildArch, probably more).
* Translate PACKAGECONFIG settings as bcond.  This will mean saving the
  PACKAGECONFIG value before clearing it, then iterating through the saved
  values and setting the dependencies and configure options as required.