========================
Packaging Meta Data Unit
========================

The packaging meta-data unit describes system-level dependencies of a provider
in a machine readable way. Dependencies can be specified separately for
different distributions. Dependencies can also be specified for a common base
distribution (e.g. for Debian rather than Ubuntu). The use of packaging
meta-data units can greatly simplify management of dependencies of binary
packages as it brings those decisions closer to the changes to the actual
provider and makes package management largely automatic.

File format and location
------------------------

Packaging meta-data units are regular Checkbox units and are contained and
shipped with Checkbox providers. In other words, they are just the same as job
and test plan units, for example.

Fields
------

Following fields may be used by a manifest entry unit.

.. _Packaging Meta Data os-id field:

``os-id``:
    (mandatory) - the identifier of the operating system this rule applies to.
    This is the same value as the ``ID`` field in the file ``/etc/os-release``.
    Typical values include ``debian``, ``ubuntu`` or ``fedora``.

.. _Packaging Meta Data os-version-id field:

``os-version-id``:
    (optional) - the identifier of the specific version of the operating system
    this rule applies to. This is the same as the ``VERSION_ID`` field in the
    file ``/etc/os-release``. If this field is not present then the rule
    applies to all versions of a given operating system.

    It is also possible to specify a version comparison operator, such as
    ``>=`` or ``<=``. This is useful when a rule applies to a range of versions.
    For example, ``os-version-id: >= 20.04`` will match all versions of Ubuntu
    greater than or equal to 20.04.

The remaining fields are custom and depend on the packaging driver. The values
for **Debian** are:

.. _Packaging Meta Data Depends field:

``Depends``:
    (optional) - a comma separated list of dependencies for the binary package.
    The syntax is the same as in normal Debian control files (including package
    version dependencies). This field can be split into multiple lines, for
    readability, as newlines are discarded.
    In order to avoid unwanted dependency repetitions, this field is declared as
    an unique value for validation.


.. _Packaging Meta Data Suggests field:

``Suggests``:
    (optional) - same as ``Depends``.

.. _Packaging Meta Data Recommends field:

``Recommends``:
    (optional) - same as ``Depends``.

Matching Packaging Meta-Data Units
----------------------------------

The base Linux distribution driver parses the ``/etc/os-release`` file, looks
at the ``ID``, ``ID_VERSION`` and optionally the ``ID_LIKE`` fields.  They are
used as a standard way to determine the distribution for which packaging
meta-data is being collected for.

The *id and version match* strategy requires that both the ``os-id`` and
``os-dependencies`` fields are present and that they match the ``ID`` and
``ID_VERSION`` values. This strategy allows the test maintainer to express each
dependency accurately for each operating system they wish to support.

The *id match* strategy is only used when the ``os-version`` is not defined.
It is useful when a single definition is applicable to many subsequent
releases.  This is especially useful when job works well with sufficiently old
version of a third party dependency and there is no need to repeatedly re-state
the same dependency for each later release of the operating system.

The *id_like match* strategy is only used as a last resort and can be seen as a
weaker *id match* strategy. This  time the ``os-id`` field is compared to the
``ID_LIKE`` field (if present). It is useful for working with Debian
derivatives, like Ubuntu.

Each matching packaging meta-data unit is then passed to the driver to generate
packaging meta-data.

Examples
--------

This is an example packaging meta-data unit, as taken from the resource provider::

    unit: packaging meta-data
    os-id: debian
    Depends:
     python3-checkbox-support (>= 0.2),
     python3 (>= 3.2),
    Recommends:
     dmidecode,
     dpkg (>= 1.13),
     lsb-release,
     wodim

This will cause the binary provider package to depend on the appropriate
version of ``python3-checkbox-support`` and ``python3`` in both *Debian*,
*Ubuntu* and, for example, *Elementary OS*. In addition the package will
recommend some utilities that are used by some of the jobs contained in this
provider.

If we want a version of the package to be available in Ubuntu 20.04 or newer,
we can use the following packaging meta-data unit::

    unit: packaging meta-data
    os-id: ubuntu
    os-version-id: >= 20.04
    Depends: libsvm3


Using Packaging Meta-Data in Debian
-----------------------------------

To make use of the packaging meta-data, follow those steps:

- Ensure that ``/etc/os-release`` exists in your build chroot. On Debian it is
  a part of the ``base-files`` package which is not something you have to worry
  about but other distributions may use different strategies.
- Mark the binary package that contains the provider with the
  ``X-Plainbox-Provider: yes`` header.
- Add the ``${plainbox:Depends}``, ``${plainbox:Recommends}`` and
  ``${plainbox:Suggests}`` variables to the binary package that contains the
  provider.
- Override the gen_control debhelper rule and run the ``python3 manage.py
  packaging`` command in addition to running ``dh_gencontrol``::

    override_dh_gencontrol:
        python3 manage.py packaging
        dh_gencontrol