Managing comps data for tags ============================ Koji can record comps data for each tag and uses that data to write a comps file whenever it generates a yum repo for that tag. This document describes how this data is stored, how to read it, and how to change it. For background on comps files, see * https://dnf5.readthedocs.io/en/latest/misc/comps.7.html * https://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups The comps data *affects how rpm builds are performed*. Various buildroots generated by Koji use these groups for their base install. E.g. * rpm builds use the ``build`` group * source rpm builds use the ``srpm-build`` group * maven builds use the ``maven-build`` group * wrapper rpm builds use the ``wrapper-rpm-build`` group * appliance builds use the ``appliance-build`` group * livecd builds use the ``livecd-build`` group * livemedia builds use the ``livemedia-build`` group Reading the data ---------------- The ``koji list-groups`` cli command will output the comps data for a given tag .. code-block:: text Usage: koji list-groups [options] [] (Specify the --help global option for a list of other help options) Options: -h, --help show this help message and exit --event=EVENT# query at event --ts=TIMESTAMP query at last event before timestamp --repo=REPO# query at event for a repo --show-blocked Show blocked packages and groups The command will optionally accept a group name to limit the output to a single group. Like many other types of data in Koji, the comps data is versioned and Koji remembers its history. The ``--event/--ts/--repo`` options can be used to query this data from an earlier point in time. The ``show-blocked`` option will include blocked entries in the output. Alternately ``show-groups`` command can be used to present the groups data in different formats. This command is a historical oddity, but still useful to export the data in comps format. Example ------- The following command prints the srpm-build group data for the f41-build tag. .. code-block:: text $ koji list-groups f41-build srpm-build srpm-build [f41] bash: None, mandatory [f41] fedora-release: None, mandatory [f41] fedpkg-minimal: None, mandatory [f41] glibc-minimal-langpack: None, mandatory [f41] gnupg2: None, mandatory [f41] redhat-rpm-config: None, mandatory [f41] rpm-build: None, mandatory [f41] shadow-utils: None, mandatory [f41] Because our command included a specific group name, the command only outputs that one group. Under this group, we see the list of packages in the group and their parameters. The bracketed value at the end shows the tag that the entry is inherited from. Groups data and inheritance --------------------------- Like most other data associated with tags, groups data is inheritable. Because the groups data is complex, so is the inheritance. The groups data is inherited piecemeal, with individual groups, group package entries, and group dependencies separately inheritable. You can prevent an entry from being inherited by blocking it. This can be done via the ``block-group``, ``block-group-pkg``, and ``block-group-req`` commands respectively (and undone with the corresponding unblock command). As noted above, you can see which tags an entry comes from via the ``list-groups`` command. So, a given tag will have a list of groups that includes inherited entries. Each of those groups will have a list of packages and a list of group dependencies which include inherited entries. For admin sanity, we recommend defining a comps in a base tag in your inheritance and keeping adjustments in child tags to a minimum. A common case is to add additional packages to the build group for a specialized build tag. Changing comps data ------------------- You can add, remove, block, and unblock individual entries with the relevant command .. code-block:: text add-group Add a group to a tag remove-group Remove group from tag block-group Block group in tag unblock-group Unblock a group from tag add-group-pkg Add a package to a group's package listing remove-group-pkg Remove packages from a group's package listing block-group-pkg Block a package from a group's package listing unblock-group-pkg Unblock a package from a group's package listing add-group-req Add a group to a group's required list block-group-req Block a group's requirement listing remove-group-req Remove entries from a group's requirement listing unblock-group-req Unblock a group's requirement listing Additionally, you can also import groups data directly from a comps file with the ``import-comps`` command. This is useful when setting up a new tag from scratch. .. code-block:: text Usage: koji import-comps [options] (Specify the --help global option for a list of other help options) Options: -h, --help show this help message and exit --force force import Blocking vs removing -------------------- The various remove commands remove a specific entry from a specific tag. They will fail if the entry is not actually in the specified tag. This commonly happens when an entry is inherited. When your tag has an inherited comps entry that you want to remove, you have two options: * block the entry in the tag * remove the entry from the ancestor tag it is inherited from It is generally safest to block, as this only affects the tag of concern. Removing the entry in an ancestor could affect other tags negatively. However, there are certainly cases where it makes sense to remove the entry from the ancestor. Group dependencies ------------------ For historical reasons, Koji's comps data allows specifying group dependecies/requirements. This is antiquated feature of comps that is longer used by dnf, so in practice there is no need to specify such entries (i.e. the various ``*-req`` commands).