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

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

Usage: koji list-groups [options] <tag> [<group>]
(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.

$ 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

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.

Usage: koji import-comps [options] <file> <tag>
(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).